Skip to content

anymap_ts module

base

Base MapWidget class for all map implementations.

MapWidget (AnyWidget)

Base class for interactive map widgets.

This class provides the core functionality for Python-JavaScript communication using anywidget's traitlet synchronization system.

Source code in anymap_ts/base.py
class MapWidget(anywidget.AnyWidget):
    """Base class for interactive map widgets.

    This class provides the core functionality for Python-JavaScript communication
    using anywidget's traitlet synchronization system.
    """

    # Synchronized traits for map state
    center = traitlets.List([0.0, 0.0]).tag(sync=True)
    zoom = traitlets.Float(2.0).tag(sync=True)
    width = traitlets.Unicode("100%").tag(sync=True)
    height = traitlets.Unicode("400px").tag(sync=True)
    style = traitlets.Union([traitlets.Unicode(), traitlets.Dict()]).tag(sync=True)
    max_pitch = traitlets.Float(85.0).tag(sync=True)

    # JavaScript method call queue
    _js_calls = traitlets.List([]).tag(sync=True)
    _js_method_counter = traitlets.Int(0)

    # Events from JavaScript
    _js_events = traitlets.List([]).tag(sync=True)

    # State persistence for layers, sources, and controls
    _layers = traitlets.Dict({}).tag(sync=True)
    _sources = traitlets.Dict({}).tag(sync=True)
    _controls = traitlets.Dict({}).tag(sync=True)

    # Interaction state
    clicked = traitlets.Dict({}).tag(sync=True)
    current_bounds = traitlets.List([]).tag(sync=True)
    current_center = traitlets.List([]).tag(sync=True)
    current_zoom = traitlets.Float(0.0).tag(sync=True)

    # Drawing data
    _draw_data = traitlets.Dict({}).tag(sync=True)

    # Queried features (set by JS query methods)
    _queried_features = traitlets.Dict({}).tag(sync=True)

    def __init__(self, **kwargs):
        """Initialize the MapWidget.

        Args:
            **kwargs: Additional widget arguments
        """
        super().__init__(**kwargs)
        self._event_handlers: Dict[str, List[Callable]] = {}
        self.observe(self._handle_js_events, names=["_js_events"])

    def _handle_js_events(self, change: Dict[str, Any]) -> None:
        """Process events received from JavaScript.

        Args:
            change: Traitlet change dict
        """
        events = change.get("new", [])
        for event in events:
            event_type = event.get("type")
            if event_type in self._event_handlers:
                for handler in self._event_handlers[event_type]:
                    try:
                        handler(event.get("data"))
                    except Exception as e:
                        print(f"Error in event handler for {event_type}: {e}")
        # Clear processed events
        self._js_events = []

    def call_js_method(self, method: str, *args, **kwargs) -> None:
        """Queue a JavaScript method call.

        Args:
            method: Name of the JavaScript method to call
            *args: Positional arguments for the method
            **kwargs: Keyword arguments for the method
        """
        self._js_method_counter += 1
        call = {
            "id": self._js_method_counter,
            "method": method,
            "args": list(args),
            "kwargs": kwargs,
        }
        self._js_calls = self._js_calls + [call]

    def on_map_event(self, event_type: str, handler: Callable) -> None:
        """Register an event handler.

        Args:
            event_type: Type of event (e.g., 'click', 'moveend')
            handler: Callback function to handle the event
        """
        if event_type not in self._event_handlers:
            self._event_handlers[event_type] = []
        self._event_handlers[event_type].append(handler)

    def off_map_event(
        self, event_type: str, handler: Optional[Callable] = None
    ) -> None:
        """Unregister an event handler.

        Args:
            event_type: Type of event
            handler: Specific handler to remove. If None, removes all handlers.
        """
        if event_type in self._event_handlers:
            if handler is None:
                del self._event_handlers[event_type]
            else:
                self._event_handlers[event_type] = [
                    h for h in self._event_handlers[event_type] if h != handler
                ]

    def set_center(self, lng: float, lat: float) -> None:
        """Set the map center.

        Args:
            lng: Longitude
            lat: Latitude
        """
        self.center = [lng, lat]

    def set_zoom(self, zoom: float) -> None:
        """Set the map zoom level.

        Args:
            zoom: Zoom level
        """
        self.zoom = zoom

    def fly_to(
        self,
        lng: float,
        lat: float,
        zoom: Optional[float] = None,
        duration: int = 2000,
    ) -> None:
        """Fly to a location with animation.

        Args:
            lng: Longitude
            lat: Latitude
            zoom: Optional zoom level
            duration: Animation duration in milliseconds
        """
        self.call_js_method("flyTo", lng, lat, zoom=zoom, duration=duration)

    def fit_bounds(
        self,
        bounds: List[float],
        padding: int = 50,
        duration: int = 1000,
    ) -> None:
        """Fit the map to the given bounds.

        Args:
            bounds: [west, south, east, north] bounds
            padding: Padding in pixels
            duration: Animation duration in milliseconds
        """
        self.call_js_method("fitBounds", bounds, padding=padding, duration=duration)

    @property
    def viewstate(self) -> Dict[str, Any]:
        """Get current view state."""
        return {
            "center": self.current_center or self.center,
            "zoom": self.current_zoom or self.zoom,
            "bounds": self.current_bounds,
        }

    def _generate_html_template(self) -> str:
        """Generate HTML template for standalone export.

        Override in subclasses for library-specific templates.
        """
        raise NotImplementedError("Subclasses must implement _generate_html_template")

    def to_html(
        self,
        filepath: Optional[Union[str, Path]] = None,
        title: str = "Interactive Map",
    ) -> Optional[str]:
        """Export map to standalone HTML file.

        Args:
            filepath: Path to save the HTML file. If None, returns HTML string.
            title: Title for the HTML page.

        Returns:
            HTML string if filepath is None, otherwise None.
        """
        html = self._generate_html_template()
        html = html.replace("{{title}}", title)

        if filepath:
            Path(filepath).write_text(html, encoding="utf-8")
            return None
        return html

viewstate: Dict[str, Any] property readonly

Get current view state.

__init__(self, **kwargs) special

Initialize the MapWidget.

Parameters:

Name Type Description Default
**kwargs

Additional widget arguments

{}
Source code in anymap_ts/base.py
def __init__(self, **kwargs):
    """Initialize the MapWidget.

    Args:
        **kwargs: Additional widget arguments
    """
    super().__init__(**kwargs)
    self._event_handlers: Dict[str, List[Callable]] = {}
    self.observe(self._handle_js_events, names=["_js_events"])

call_js_method(self, method, *args, **kwargs)

Queue a JavaScript method call.

Parameters:

Name Type Description Default
method str

Name of the JavaScript method to call

required
*args

Positional arguments for the method

()
**kwargs

Keyword arguments for the method

{}
Source code in anymap_ts/base.py
def call_js_method(self, method: str, *args, **kwargs) -> None:
    """Queue a JavaScript method call.

    Args:
        method: Name of the JavaScript method to call
        *args: Positional arguments for the method
        **kwargs: Keyword arguments for the method
    """
    self._js_method_counter += 1
    call = {
        "id": self._js_method_counter,
        "method": method,
        "args": list(args),
        "kwargs": kwargs,
    }
    self._js_calls = self._js_calls + [call]

fit_bounds(self, bounds, padding=50, duration=1000)

Fit the map to the given bounds.

Parameters:

Name Type Description Default
bounds List[float]

[west, south, east, north] bounds

required
padding int

Padding in pixels

50
duration int

Animation duration in milliseconds

1000
Source code in anymap_ts/base.py
def fit_bounds(
    self,
    bounds: List[float],
    padding: int = 50,
    duration: int = 1000,
) -> None:
    """Fit the map to the given bounds.

    Args:
        bounds: [west, south, east, north] bounds
        padding: Padding in pixels
        duration: Animation duration in milliseconds
    """
    self.call_js_method("fitBounds", bounds, padding=padding, duration=duration)

fly_to(self, lng, lat, zoom=None, duration=2000)

Fly to a location with animation.

Parameters:

Name Type Description Default
lng float

Longitude

required
lat float

Latitude

required
zoom Optional[float]

Optional zoom level

None
duration int

Animation duration in milliseconds

2000
Source code in anymap_ts/base.py
def fly_to(
    self,
    lng: float,
    lat: float,
    zoom: Optional[float] = None,
    duration: int = 2000,
) -> None:
    """Fly to a location with animation.

    Args:
        lng: Longitude
        lat: Latitude
        zoom: Optional zoom level
        duration: Animation duration in milliseconds
    """
    self.call_js_method("flyTo", lng, lat, zoom=zoom, duration=duration)

off_map_event(self, event_type, handler=None)

Unregister an event handler.

Parameters:

Name Type Description Default
event_type str

Type of event

required
handler Optional[Callable]

Specific handler to remove. If None, removes all handlers.

None
Source code in anymap_ts/base.py
def off_map_event(
    self, event_type: str, handler: Optional[Callable] = None
) -> None:
    """Unregister an event handler.

    Args:
        event_type: Type of event
        handler: Specific handler to remove. If None, removes all handlers.
    """
    if event_type in self._event_handlers:
        if handler is None:
            del self._event_handlers[event_type]
        else:
            self._event_handlers[event_type] = [
                h for h in self._event_handlers[event_type] if h != handler
            ]

on_map_event(self, event_type, handler)

Register an event handler.

Parameters:

Name Type Description Default
event_type str

Type of event (e.g., 'click', 'moveend')

required
handler Callable

Callback function to handle the event

required
Source code in anymap_ts/base.py
def on_map_event(self, event_type: str, handler: Callable) -> None:
    """Register an event handler.

    Args:
        event_type: Type of event (e.g., 'click', 'moveend')
        handler: Callback function to handle the event
    """
    if event_type not in self._event_handlers:
        self._event_handlers[event_type] = []
    self._event_handlers[event_type].append(handler)

set_center(self, lng, lat)

Set the map center.

Parameters:

Name Type Description Default
lng float

Longitude

required
lat float

Latitude

required
Source code in anymap_ts/base.py
def set_center(self, lng: float, lat: float) -> None:
    """Set the map center.

    Args:
        lng: Longitude
        lat: Latitude
    """
    self.center = [lng, lat]

set_zoom(self, zoom)

Set the map zoom level.

Parameters:

Name Type Description Default
zoom float

Zoom level

required
Source code in anymap_ts/base.py
def set_zoom(self, zoom: float) -> None:
    """Set the map zoom level.

    Args:
        zoom: Zoom level
    """
    self.zoom = zoom

to_html(self, filepath=None, title='Interactive Map')

Export map to standalone HTML file.

Parameters:

Name Type Description Default
filepath Optional[Union[str, Path]]

Path to save the HTML file. If None, returns HTML string.

None
title str

Title for the HTML page.

'Interactive Map'

Returns:

Type Description
Optional[str]

HTML string if filepath is None, otherwise None.

Source code in anymap_ts/base.py
def to_html(
    self,
    filepath: Optional[Union[str, Path]] = None,
    title: str = "Interactive Map",
) -> Optional[str]:
    """Export map to standalone HTML file.

    Args:
        filepath: Path to save the HTML file. If None, returns HTML string.
        title: Title for the HTML page.

    Returns:
        HTML string if filepath is None, otherwise None.
    """
    html = self._generate_html_template()
    html = html.replace("{{title}}", title)

    if filepath:
        Path(filepath).write_text(html, encoding="utf-8")
        return None
    return html

basemaps

Basemap provider utilities.

get_basemap_names()

Get list of available basemap names.

Returns:

Type Description
list

List of basemap provider names

Source code in anymap_ts/basemaps.py
def get_basemap_names() -> list:
    """Get list of available basemap names.

    Returns:
        List of basemap provider names
    """
    return list(xyz.flatten().keys())

get_basemap_url(name)

Get tile URL and attribution for a named basemap.

Parameters:

Name Type Description Default
name str

Basemap provider name (e.g., "OpenStreetMap", "CartoDB.Positron")

required

Returns:

Type Description
Tuple[str, str]

Tuple of (tile_url, attribution)

Exceptions:

Type Description
ValueError

If basemap name is not found

Source code in anymap_ts/basemaps.py
def get_basemap_url(name: str) -> Tuple[str, str]:
    """Get tile URL and attribution for a named basemap.

    Args:
        name: Basemap provider name (e.g., "OpenStreetMap", "CartoDB.Positron")

    Returns:
        Tuple of (tile_url, attribution)

    Raises:
        ValueError: If basemap name is not found
    """
    # Handle shortcuts
    if name in BASEMAP_SHORTCUTS:
        name = BASEMAP_SHORTCUTS[name]

    # Handle dot notation for nested providers
    parts = name.split(".")
    provider = xyz
    for part in parts:
        provider = getattr(provider, part, None)
        if provider is None:
            raise ValueError(f"Unknown basemap: {name}")

    url = provider.build_url()
    attribution = provider.get("attribution", "")

    return url, attribution

get_maplibre_style(name)

Get MapLibre style URL by name.

Parameters:

Name Type Description Default
name str

Style name (e.g., "positron", "dark-matter")

required

Returns:

Type Description
str

Style URL

Exceptions:

Type Description
ValueError

If style name is not found

Source code in anymap_ts/basemaps.py
def get_maplibre_style(name: str) -> str:
    """Get MapLibre style URL by name.

    Args:
        name: Style name (e.g., "positron", "dark-matter")

    Returns:
        Style URL

    Raises:
        ValueError: If style name is not found
    """
    name_lower = name.lower().replace("_", "-")
    if name_lower in MAPLIBRE_STYLES:
        return MAPLIBRE_STYLES[name_lower]
    # Assume it's already a URL
    if name.startswith("http"):
        return name
    raise ValueError(f"Unknown MapLibre style: {name}")

cesium

Cesium 3D globe widget implementation.

CesiumMap (MapWidget)

Interactive 3D globe widget using Cesium.

This class provides a Python interface to Cesium for 3D globe visualization with terrain, 3D Tiles, and imagery layer support.

Examples:

>>> from anymap_ts import CesiumMap
>>> m = CesiumMap(center=[-122.4, 37.8], zoom=10)
>>> m.set_terrain()  # Enable Cesium World Terrain
>>> m.add_3d_tileset(url="path/to/tileset.json")
>>> m
Source code in anymap_ts/cesium.py
class CesiumMap(MapWidget):
    """Interactive 3D globe widget using Cesium.

    This class provides a Python interface to Cesium for 3D globe
    visualization with terrain, 3D Tiles, and imagery layer support.

    Example:
        >>> from anymap_ts import CesiumMap
        >>> m = CesiumMap(center=[-122.4, 37.8], zoom=10)
        >>> m.set_terrain()  # Enable Cesium World Terrain
        >>> m.add_3d_tileset(url="path/to/tileset.json")
        >>> m
    """

    # ESM module for frontend
    _esm = STATIC_DIR / "cesium.js"
    _css = STATIC_DIR / "cesium.css"

    # Cesium-specific traits
    access_token = traitlets.Unicode("").tag(sync=True)

    # Camera position traits
    camera_height = traitlets.Float(10000000).tag(sync=True)
    heading = traitlets.Float(0.0).tag(sync=True)
    pitch = traitlets.Float(-90.0).tag(sync=True)
    roll = traitlets.Float(0.0).tag(sync=True)

    # Terrain
    terrain_enabled = traitlets.Bool(False).tag(sync=True)

    def __init__(
        self,
        center: Tuple[float, float] = (0.0, 0.0),
        zoom: float = 2.0,
        width: str = "100%",
        height: str = "600px",
        access_token: Optional[str] = None,
        terrain: bool = False,
        **kwargs,
    ):
        """Initialize a Cesium 3D globe.

        Args:
            center: Globe center as (longitude, latitude).
            zoom: Initial zoom level (converted to camera height).
            width: Widget width as CSS string.
            height: Widget height as CSS string.
            access_token: Cesium Ion access token (uses CESIUM_TOKEN env var if not provided).
            terrain: Whether to enable terrain on initialization.
            **kwargs: Additional widget arguments.
        """
        # Get access token from env if not provided
        if access_token is None:
            access_token = get_cesium_token()

        super().__init__(
            center=list(center),
            zoom=zoom,
            width=width,
            height=height,
            access_token=access_token,
            terrain_enabled=terrain,
            **kwargs,
        )

        # Enable terrain if requested
        if terrain:
            self.set_terrain()

    # -------------------------------------------------------------------------
    # Basemap/Imagery Methods
    # -------------------------------------------------------------------------

    def add_basemap(
        self,
        basemap: str = "OpenStreetMap",
        **kwargs,
    ) -> None:
        """Add a basemap imagery layer.

        Args:
            basemap: Name of basemap (e.g., "OpenStreetMap", "Bing").
            **kwargs: Additional options.
        """
        # Common basemap URLs
        basemap_urls = {
            "OpenStreetMap": "https://tile.openstreetmap.org/{z}/{x}/{y}.png",
            "CartoDB.Positron": "https://a.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png",
            "CartoDB.DarkMatter": "https://a.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}.png",
            "Stamen.Terrain": "https://tiles.stadiamaps.com/tiles/stamen_terrain/{z}/{x}/{y}.png",
        }

        url = basemap_urls.get(basemap, basemap_urls["OpenStreetMap"])

        self.call_js_method("addBasemap", url, name=basemap, **kwargs)

    def add_imagery_layer(
        self,
        url: str,
        name: Optional[str] = None,
        layer_type: str = "xyz",
        alpha: float = 1.0,
        **kwargs,
    ) -> None:
        """Add an imagery layer.

        Args:
            url: Imagery URL or service endpoint.
            name: Layer name.
            layer_type: Type of imagery ('xyz', 'wms', 'wmts', 'arcgis').
            alpha: Layer opacity (0-1).
            **kwargs: Additional options (layers, parameters for WMS, etc.).
        """
        layer_id = name or f"imagery-{len(self._layers)}"

        self.call_js_method(
            "addImageryLayer",
            url=url,
            name=layer_id,
            type=layer_type,
            alpha=alpha,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {"id": layer_id, "type": "imagery"},
        }

    def remove_imagery_layer(self, name: str) -> None:
        """Remove an imagery layer.

        Args:
            name: Layer name to remove.
        """
        if name in self._layers:
            layers = dict(self._layers)
            del layers[name]
            self._layers = layers
        self.call_js_method("removeImageryLayer", name)

    # -------------------------------------------------------------------------
    # Terrain Methods
    # -------------------------------------------------------------------------

    def set_terrain(
        self,
        url: Optional[str] = None,
        request_vertex_normals: bool = True,
        request_water_mask: bool = True,
    ) -> None:
        """Enable terrain.

        Args:
            url: Terrain provider URL. If None, uses Cesium World Terrain (requires Ion token).
            request_vertex_normals: Request vertex normals for lighting.
            request_water_mask: Request water mask for water effects.
        """
        self.terrain_enabled = True
        self.call_js_method(
            "setTerrain",
            url=url or "cesium-world-terrain",
            requestVertexNormals=request_vertex_normals,
            requestWaterMask=request_water_mask,
        )

    def remove_terrain(self) -> None:
        """Disable terrain and use ellipsoid."""
        self.terrain_enabled = False
        self.call_js_method("removeTerrain")

    # -------------------------------------------------------------------------
    # 3D Tiles Methods
    # -------------------------------------------------------------------------

    def add_3d_tileset(
        self,
        url: Union[str, int],
        name: Optional[str] = None,
        maximum_screen_space_error: float = 16,
        fly_to: bool = True,
        **kwargs,
    ) -> None:
        """Add a 3D Tileset.

        Args:
            url: URL to tileset.json or Cesium Ion asset ID.
            name: Tileset name.
            maximum_screen_space_error: Maximum screen space error for LOD.
            fly_to: Whether to fly to the tileset after loading.
            **kwargs: Additional options.
        """
        layer_id = name or f"tileset-{len(self._layers)}"

        self.call_js_method(
            "add3DTileset",
            url=str(url),
            name=layer_id,
            maximumScreenSpaceError=maximum_screen_space_error,
            flyTo=fly_to,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {"id": layer_id, "type": "3dtiles"},
        }

    def remove_3d_tileset(self, name: str) -> None:
        """Remove a 3D Tileset.

        Args:
            name: Tileset name to remove.
        """
        if name in self._layers:
            layers = dict(self._layers)
            del layers[name]
            self._layers = layers
        self.call_js_method("remove3DTileset", name)

    # -------------------------------------------------------------------------
    # GeoJSON Methods
    # -------------------------------------------------------------------------

    def add_geojson(
        self,
        data: Any,
        name: Optional[str] = None,
        stroke: str = "#3388ff",
        stroke_width: float = 2,
        fill: str = "rgba(51, 136, 255, 0.5)",
        clamp_to_ground: bool = True,
        fly_to: bool = True,
        **kwargs,
    ) -> None:
        """Add GeoJSON data.

        Args:
            data: GeoJSON dict or file path.
            name: Data source name.
            stroke: Stroke color.
            stroke_width: Stroke width.
            fill: Fill color.
            clamp_to_ground: Whether to clamp features to terrain.
            fly_to: Whether to fly to the data after loading.
            **kwargs: Additional options.
        """
        geojson = to_geojson(data)
        layer_id = name or f"geojson-{len(self._layers)}"

        self.call_js_method(
            "addGeoJSON",
            data=geojson,
            name=layer_id,
            stroke=stroke,
            strokeWidth=stroke_width,
            fill=fill,
            clampToGround=clamp_to_ground,
            flyTo=fly_to,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {"id": layer_id, "type": "geojson"},
        }

    def remove_data_source(self, name: str) -> None:
        """Remove a data source (GeoJSON, etc.).

        Args:
            name: Data source name to remove.
        """
        if name in self._layers:
            layers = dict(self._layers)
            del layers[name]
            self._layers = layers
        self.call_js_method("removeDataSource", name)

    # -------------------------------------------------------------------------
    # Camera Methods
    # -------------------------------------------------------------------------

    def fly_to(
        self,
        lng: float,
        lat: float,
        height: Optional[float] = None,
        zoom: Optional[float] = None,
        heading: float = 0,
        pitch: float = -90,
        roll: float = 0,
        duration: float = 2,
    ) -> None:
        """Fly to a location.

        Args:
            lng: Target longitude.
            lat: Target latitude.
            height: Camera height in meters (overrides zoom).
            zoom: Zoom level (converted to height if height not provided).
            heading: Camera heading in degrees.
            pitch: Camera pitch in degrees (default -90 = looking down).
            roll: Camera roll in degrees.
            duration: Flight duration in seconds.
        """
        self.call_js_method(
            "flyTo",
            lng,
            lat,
            height=height,
            zoom=zoom,
            heading=heading,
            pitch=pitch,
            roll=roll,
            duration=duration,
        )

    def zoom_to(self, target: str) -> None:
        """Zoom to a layer or data source.

        Args:
            target: Name of the layer or data source to zoom to.
        """
        self.call_js_method("zoomTo", target=target)

    def set_camera(
        self,
        longitude: float = 0,
        latitude: float = 0,
        height: float = 10000000,
        heading: float = 0,
        pitch: float = -90,
        roll: float = 0,
    ) -> None:
        """Set the camera position immediately (no animation).

        Args:
            longitude: Camera longitude.
            latitude: Camera latitude.
            height: Camera height in meters.
            heading: Camera heading in degrees.
            pitch: Camera pitch in degrees.
            roll: Camera roll in degrees.
        """
        self.call_js_method(
            "setCamera",
            longitude=longitude,
            latitude=latitude,
            height=height,
            heading=heading,
            pitch=pitch,
            roll=roll,
        )

    def reset_view(self, duration: float = 2) -> None:
        """Reset camera to home position.

        Args:
            duration: Animation duration in seconds.
        """
        self.call_js_method("resetView", duration=duration)

    # -------------------------------------------------------------------------
    # Layer Management
    # -------------------------------------------------------------------------

    def set_visibility(self, name: str, visible: bool) -> None:
        """Set layer visibility.

        Args:
            name: Layer name.
            visible: Whether layer should be visible.
        """
        self.call_js_method("setVisibility", name, visible)

    def set_opacity(self, name: str, opacity: float) -> None:
        """Set layer opacity (imagery layers only).

        Args:
            name: Layer name.
            opacity: Opacity value (0-1).
        """
        self.call_js_method("setOpacity", name, opacity)

    # -------------------------------------------------------------------------
    # HTML Export
    # -------------------------------------------------------------------------

    def _generate_html_template(self) -> str:
        """Generate standalone HTML for the globe."""
        template_path = Path(__file__).parent / "templates" / "cesium.html"

        if template_path.exists():
            template = template_path.read_text(encoding="utf-8")
        else:
            template = self._get_default_template()

        state = {
            "center": self.center,
            "zoom": self.zoom,
            "access_token": self.access_token,
            "terrain_enabled": self.terrain_enabled,
            "width": self.width,
            "height": self.height,
            "layers": self._layers,
            "js_calls": self._js_calls,
        }

        template = template.replace("{{state}}", json.dumps(state, indent=2))
        template = template.replace("{{access_token}}", self.access_token)
        return template

    def _get_default_template(self) -> str:
        """Get default HTML template."""
        return """<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>Cesium Globe</title>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cesium.com/downloads/cesiumjs/releases/1.120/Build/Cesium/Cesium.js"></script>
    <link href="https://cesium.com/downloads/cesiumjs/releases/1.120/Build/Cesium/Widgets/widgets.css" rel="stylesheet">
    <style>
        * { margin: 0; padding: 0; box-sizing: border-box; }
        html, body { height: 100%; }
        #cesiumContainer { position: absolute; top: 0; bottom: 0; width: 100%; }
    </style>
</head>
<body>
    <div id="cesiumContainer"></div>
    <script>
        const state = {{state}};

        if (state.access_token) {
            Cesium.Ion.defaultAccessToken = state.access_token;
        }

        const viewer = new Cesium.Viewer('cesiumContainer', {
            baseLayerPicker: false,
            geocoder: false,
            homeButton: false,
            sceneModePicker: false,
            navigationHelpButton: false,
            animation: false,
            timeline: false
        });

        for (const call of state.js_calls || []) {
            executeMethod(call.method, call.args, call.kwargs);
        }

        function executeMethod(method, args, kwargs) {
            console.log('Executing:', method, args, kwargs);
        }
    </script>
</body>
</html>"""

__init__(self, center=(0.0, 0.0), zoom=2.0, width='100%', height='600px', access_token=None, terrain=False, **kwargs) special

Initialize a Cesium 3D globe.

Parameters:

Name Type Description Default
center Tuple[float, float]

Globe center as (longitude, latitude).

(0.0, 0.0)
zoom float

Initial zoom level (converted to camera height).

2.0
width str

Widget width as CSS string.

'100%'
height str

Widget height as CSS string.

'600px'
access_token Optional[str]

Cesium Ion access token (uses CESIUM_TOKEN env var if not provided).

None
terrain bool

Whether to enable terrain on initialization.

False
**kwargs

Additional widget arguments.

{}
Source code in anymap_ts/cesium.py
def __init__(
    self,
    center: Tuple[float, float] = (0.0, 0.0),
    zoom: float = 2.0,
    width: str = "100%",
    height: str = "600px",
    access_token: Optional[str] = None,
    terrain: bool = False,
    **kwargs,
):
    """Initialize a Cesium 3D globe.

    Args:
        center: Globe center as (longitude, latitude).
        zoom: Initial zoom level (converted to camera height).
        width: Widget width as CSS string.
        height: Widget height as CSS string.
        access_token: Cesium Ion access token (uses CESIUM_TOKEN env var if not provided).
        terrain: Whether to enable terrain on initialization.
        **kwargs: Additional widget arguments.
    """
    # Get access token from env if not provided
    if access_token is None:
        access_token = get_cesium_token()

    super().__init__(
        center=list(center),
        zoom=zoom,
        width=width,
        height=height,
        access_token=access_token,
        terrain_enabled=terrain,
        **kwargs,
    )

    # Enable terrain if requested
    if terrain:
        self.set_terrain()

add_3d_tileset(self, url, name=None, maximum_screen_space_error=16, fly_to=True, **kwargs)

Add a 3D Tileset.

Parameters:

Name Type Description Default
url Union[str, int]

URL to tileset.json or Cesium Ion asset ID.

required
name Optional[str]

Tileset name.

None
maximum_screen_space_error float

Maximum screen space error for LOD.

16
fly_to bool

Whether to fly to the tileset after loading.

True
**kwargs

Additional options.

{}
Source code in anymap_ts/cesium.py
def add_3d_tileset(
    self,
    url: Union[str, int],
    name: Optional[str] = None,
    maximum_screen_space_error: float = 16,
    fly_to: bool = True,
    **kwargs,
) -> None:
    """Add a 3D Tileset.

    Args:
        url: URL to tileset.json or Cesium Ion asset ID.
        name: Tileset name.
        maximum_screen_space_error: Maximum screen space error for LOD.
        fly_to: Whether to fly to the tileset after loading.
        **kwargs: Additional options.
    """
    layer_id = name or f"tileset-{len(self._layers)}"

    self.call_js_method(
        "add3DTileset",
        url=str(url),
        name=layer_id,
        maximumScreenSpaceError=maximum_screen_space_error,
        flyTo=fly_to,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {"id": layer_id, "type": "3dtiles"},
    }

add_basemap(self, basemap='OpenStreetMap', **kwargs)

Add a basemap imagery layer.

Parameters:

Name Type Description Default
basemap str

Name of basemap (e.g., "OpenStreetMap", "Bing").

'OpenStreetMap'
**kwargs

Additional options.

{}
Source code in anymap_ts/cesium.py
def add_basemap(
    self,
    basemap: str = "OpenStreetMap",
    **kwargs,
) -> None:
    """Add a basemap imagery layer.

    Args:
        basemap: Name of basemap (e.g., "OpenStreetMap", "Bing").
        **kwargs: Additional options.
    """
    # Common basemap URLs
    basemap_urls = {
        "OpenStreetMap": "https://tile.openstreetmap.org/{z}/{x}/{y}.png",
        "CartoDB.Positron": "https://a.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png",
        "CartoDB.DarkMatter": "https://a.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}.png",
        "Stamen.Terrain": "https://tiles.stadiamaps.com/tiles/stamen_terrain/{z}/{x}/{y}.png",
    }

    url = basemap_urls.get(basemap, basemap_urls["OpenStreetMap"])

    self.call_js_method("addBasemap", url, name=basemap, **kwargs)

add_geojson(self, data, name=None, stroke='#3388ff', stroke_width=2, fill='rgba(51, 136, 255, 0.5)', clamp_to_ground=True, fly_to=True, **kwargs)

Add GeoJSON data.

Parameters:

Name Type Description Default
data Any

GeoJSON dict or file path.

required
name Optional[str]

Data source name.

None
stroke str

Stroke color.

'#3388ff'
stroke_width float

Stroke width.

2
fill str

Fill color.

'rgba(51, 136, 255, 0.5)'
clamp_to_ground bool

Whether to clamp features to terrain.

True
fly_to bool

Whether to fly to the data after loading.

True
**kwargs

Additional options.

{}
Source code in anymap_ts/cesium.py
def add_geojson(
    self,
    data: Any,
    name: Optional[str] = None,
    stroke: str = "#3388ff",
    stroke_width: float = 2,
    fill: str = "rgba(51, 136, 255, 0.5)",
    clamp_to_ground: bool = True,
    fly_to: bool = True,
    **kwargs,
) -> None:
    """Add GeoJSON data.

    Args:
        data: GeoJSON dict or file path.
        name: Data source name.
        stroke: Stroke color.
        stroke_width: Stroke width.
        fill: Fill color.
        clamp_to_ground: Whether to clamp features to terrain.
        fly_to: Whether to fly to the data after loading.
        **kwargs: Additional options.
    """
    geojson = to_geojson(data)
    layer_id = name or f"geojson-{len(self._layers)}"

    self.call_js_method(
        "addGeoJSON",
        data=geojson,
        name=layer_id,
        stroke=stroke,
        strokeWidth=stroke_width,
        fill=fill,
        clampToGround=clamp_to_ground,
        flyTo=fly_to,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {"id": layer_id, "type": "geojson"},
    }

add_imagery_layer(self, url, name=None, layer_type='xyz', alpha=1.0, **kwargs)

Add an imagery layer.

Parameters:

Name Type Description Default
url str

Imagery URL or service endpoint.

required
name Optional[str]

Layer name.

None
layer_type str

Type of imagery ('xyz', 'wms', 'wmts', 'arcgis').

'xyz'
alpha float

Layer opacity (0-1).

1.0
**kwargs

Additional options (layers, parameters for WMS, etc.).

{}
Source code in anymap_ts/cesium.py
def add_imagery_layer(
    self,
    url: str,
    name: Optional[str] = None,
    layer_type: str = "xyz",
    alpha: float = 1.0,
    **kwargs,
) -> None:
    """Add an imagery layer.

    Args:
        url: Imagery URL or service endpoint.
        name: Layer name.
        layer_type: Type of imagery ('xyz', 'wms', 'wmts', 'arcgis').
        alpha: Layer opacity (0-1).
        **kwargs: Additional options (layers, parameters for WMS, etc.).
    """
    layer_id = name or f"imagery-{len(self._layers)}"

    self.call_js_method(
        "addImageryLayer",
        url=url,
        name=layer_id,
        type=layer_type,
        alpha=alpha,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {"id": layer_id, "type": "imagery"},
    }

fly_to(self, lng, lat, height=None, zoom=None, heading=0, pitch=-90, roll=0, duration=2)

Fly to a location.

Parameters:

Name Type Description Default
lng float

Target longitude.

required
lat float

Target latitude.

required
height Optional[float]

Camera height in meters (overrides zoom).

None
zoom Optional[float]

Zoom level (converted to height if height not provided).

None
heading float

Camera heading in degrees.

0
pitch float

Camera pitch in degrees (default -90 = looking down).

-90
roll float

Camera roll in degrees.

0
duration float

Flight duration in seconds.

2
Source code in anymap_ts/cesium.py
def fly_to(
    self,
    lng: float,
    lat: float,
    height: Optional[float] = None,
    zoom: Optional[float] = None,
    heading: float = 0,
    pitch: float = -90,
    roll: float = 0,
    duration: float = 2,
) -> None:
    """Fly to a location.

    Args:
        lng: Target longitude.
        lat: Target latitude.
        height: Camera height in meters (overrides zoom).
        zoom: Zoom level (converted to height if height not provided).
        heading: Camera heading in degrees.
        pitch: Camera pitch in degrees (default -90 = looking down).
        roll: Camera roll in degrees.
        duration: Flight duration in seconds.
    """
    self.call_js_method(
        "flyTo",
        lng,
        lat,
        height=height,
        zoom=zoom,
        heading=heading,
        pitch=pitch,
        roll=roll,
        duration=duration,
    )

remove_3d_tileset(self, name)

Remove a 3D Tileset.

Parameters:

Name Type Description Default
name str

Tileset name to remove.

required
Source code in anymap_ts/cesium.py
def remove_3d_tileset(self, name: str) -> None:
    """Remove a 3D Tileset.

    Args:
        name: Tileset name to remove.
    """
    if name in self._layers:
        layers = dict(self._layers)
        del layers[name]
        self._layers = layers
    self.call_js_method("remove3DTileset", name)

remove_data_source(self, name)

Remove a data source (GeoJSON, etc.).

Parameters:

Name Type Description Default
name str

Data source name to remove.

required
Source code in anymap_ts/cesium.py
def remove_data_source(self, name: str) -> None:
    """Remove a data source (GeoJSON, etc.).

    Args:
        name: Data source name to remove.
    """
    if name in self._layers:
        layers = dict(self._layers)
        del layers[name]
        self._layers = layers
    self.call_js_method("removeDataSource", name)

remove_imagery_layer(self, name)

Remove an imagery layer.

Parameters:

Name Type Description Default
name str

Layer name to remove.

required
Source code in anymap_ts/cesium.py
def remove_imagery_layer(self, name: str) -> None:
    """Remove an imagery layer.

    Args:
        name: Layer name to remove.
    """
    if name in self._layers:
        layers = dict(self._layers)
        del layers[name]
        self._layers = layers
    self.call_js_method("removeImageryLayer", name)

remove_terrain(self)

Disable terrain and use ellipsoid.

Source code in anymap_ts/cesium.py
def remove_terrain(self) -> None:
    """Disable terrain and use ellipsoid."""
    self.terrain_enabled = False
    self.call_js_method("removeTerrain")

reset_view(self, duration=2)

Reset camera to home position.

Parameters:

Name Type Description Default
duration float

Animation duration in seconds.

2
Source code in anymap_ts/cesium.py
def reset_view(self, duration: float = 2) -> None:
    """Reset camera to home position.

    Args:
        duration: Animation duration in seconds.
    """
    self.call_js_method("resetView", duration=duration)

set_camera(self, longitude=0, latitude=0, height=10000000, heading=0, pitch=-90, roll=0)

Set the camera position immediately (no animation).

Parameters:

Name Type Description Default
longitude float

Camera longitude.

0
latitude float

Camera latitude.

0
height float

Camera height in meters.

10000000
heading float

Camera heading in degrees.

0
pitch float

Camera pitch in degrees.

-90
roll float

Camera roll in degrees.

0
Source code in anymap_ts/cesium.py
def set_camera(
    self,
    longitude: float = 0,
    latitude: float = 0,
    height: float = 10000000,
    heading: float = 0,
    pitch: float = -90,
    roll: float = 0,
) -> None:
    """Set the camera position immediately (no animation).

    Args:
        longitude: Camera longitude.
        latitude: Camera latitude.
        height: Camera height in meters.
        heading: Camera heading in degrees.
        pitch: Camera pitch in degrees.
        roll: Camera roll in degrees.
    """
    self.call_js_method(
        "setCamera",
        longitude=longitude,
        latitude=latitude,
        height=height,
        heading=heading,
        pitch=pitch,
        roll=roll,
    )

set_opacity(self, name, opacity)

Set layer opacity (imagery layers only).

Parameters:

Name Type Description Default
name str

Layer name.

required
opacity float

Opacity value (0-1).

required
Source code in anymap_ts/cesium.py
def set_opacity(self, name: str, opacity: float) -> None:
    """Set layer opacity (imagery layers only).

    Args:
        name: Layer name.
        opacity: Opacity value (0-1).
    """
    self.call_js_method("setOpacity", name, opacity)

set_terrain(self, url=None, request_vertex_normals=True, request_water_mask=True)

Enable terrain.

Parameters:

Name Type Description Default
url Optional[str]

Terrain provider URL. If None, uses Cesium World Terrain (requires Ion token).

None
request_vertex_normals bool

Request vertex normals for lighting.

True
request_water_mask bool

Request water mask for water effects.

True
Source code in anymap_ts/cesium.py
def set_terrain(
    self,
    url: Optional[str] = None,
    request_vertex_normals: bool = True,
    request_water_mask: bool = True,
) -> None:
    """Enable terrain.

    Args:
        url: Terrain provider URL. If None, uses Cesium World Terrain (requires Ion token).
        request_vertex_normals: Request vertex normals for lighting.
        request_water_mask: Request water mask for water effects.
    """
    self.terrain_enabled = True
    self.call_js_method(
        "setTerrain",
        url=url or "cesium-world-terrain",
        requestVertexNormals=request_vertex_normals,
        requestWaterMask=request_water_mask,
    )

set_visibility(self, name, visible)

Set layer visibility.

Parameters:

Name Type Description Default
name str

Layer name.

required
visible bool

Whether layer should be visible.

required
Source code in anymap_ts/cesium.py
def set_visibility(self, name: str, visible: bool) -> None:
    """Set layer visibility.

    Args:
        name: Layer name.
        visible: Whether layer should be visible.
    """
    self.call_js_method("setVisibility", name, visible)

zoom_to(self, target)

Zoom to a layer or data source.

Parameters:

Name Type Description Default
target str

Name of the layer or data source to zoom to.

required
Source code in anymap_ts/cesium.py
def zoom_to(self, target: str) -> None:
    """Zoom to a layer or data source.

    Args:
        target: Name of the layer or data source to zoom to.
    """
    self.call_js_method("zoomTo", target=target)

get_cesium_token()

Get Cesium Ion access token from environment variable.

Returns:

Type Description
str

Cesium Ion access token or empty string if not set.

Source code in anymap_ts/cesium.py
def get_cesium_token() -> str:
    """Get Cesium Ion access token from environment variable.

    Returns:
        Cesium Ion access token or empty string if not set.
    """
    return os.environ.get("CESIUM_TOKEN", "")

deckgl

DeckGL map widget implementation extending MapLibre with deck.gl layers.

DeckGLMap (MapLibreMap)

Interactive map widget using MapLibre GL JS with deck.gl overlay.

This class extends MapLibreMap with deck.gl visualization layer support for GPU-accelerated geospatial visualizations.

Examples:

>>> from anymap_ts import DeckGLMap
>>> m = DeckGLMap(center=[-122.4, 37.8], zoom=10)
>>> m.add_scatterplot_layer(
...     data=points,
...     get_position='coordinates',
...     get_radius=100,
...     get_fill_color=[255, 0, 0]
... )
>>> m
Source code in anymap_ts/deckgl.py
class DeckGLMap(MapLibreMap):
    """Interactive map widget using MapLibre GL JS with deck.gl overlay.

    This class extends MapLibreMap with deck.gl visualization layer support
    for GPU-accelerated geospatial visualizations.

    Example:
        >>> from anymap_ts import DeckGLMap
        >>> m = DeckGLMap(center=[-122.4, 37.8], zoom=10)
        >>> m.add_scatterplot_layer(
        ...     data=points,
        ...     get_position='coordinates',
        ...     get_radius=100,
        ...     get_fill_color=[255, 0, 0]
        ... )
        >>> m
    """

    # ESM module for frontend (uses DeckGL-enabled version)
    _esm = STATIC_DIR / "deckgl.js"

    # DeckGL layer tracking
    _deck_layers = traitlets.Dict({}).tag(sync=True)

    def __init__(
        self,
        center: Tuple[float, float] = (0.0, 0.0),
        zoom: float = 2.0,
        width: str = "100%",
        height: str = "600px",
        style: Union[str, Dict] = "https://demotiles.maplibre.org/style.json",
        bearing: float = 0.0,
        pitch: float = 0.0,
        max_pitch: float = 85.0,
        controls: Optional[Dict[str, Any]] = None,
        **kwargs,
    ):
        """Initialize a DeckGL map.

        Args:
            center: Map center as (longitude, latitude).
            zoom: Initial zoom level.
            width: Map width as CSS string.
            height: Map height as CSS string.
            style: MapLibre style URL or style object.
            bearing: Map bearing in degrees.
            pitch: Map pitch in degrees.
            max_pitch: Maximum pitch angle in degrees (default: 85).
            controls: Dict of controls to add (e.g., {"navigation": True}).
            **kwargs: Additional widget arguments.
        """
        super().__init__(
            center=center,
            zoom=zoom,
            width=width,
            height=height,
            style=style,
            bearing=bearing,
            pitch=pitch,
            max_pitch=max_pitch,
            controls=controls,
            **kwargs,
        )
        self._deck_layers = {}

    # -------------------------------------------------------------------------
    # DeckGL Scatterplot Layer
    # -------------------------------------------------------------------------

    def add_scatterplot_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_position: Union[str, Callable] = "coordinates",
        get_radius: Union[float, str, Callable] = 5,
        get_fill_color: Union[List[int], str, Callable] = None,
        get_line_color: Union[List[int], str, Callable] = None,
        radius_scale: float = 1,
        radius_min_pixels: float = 1,
        radius_max_pixels: float = 100,
        line_width_min_pixels: float = 1,
        stroked: bool = True,
        filled: bool = True,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add a scatterplot layer for point visualization.

        Args:
            data: Array of data objects or GeoJSON.
            name: Layer ID.
            get_position: Accessor for point position [lng, lat].
            get_radius: Accessor for point radius.
            get_fill_color: Accessor for fill color [r, g, b, a].
            get_line_color: Accessor for stroke color [r, g, b, a].
            radius_scale: Global radius multiplier.
            radius_min_pixels: Minimum radius in pixels.
            radius_max_pixels: Maximum radius in pixels.
            line_width_min_pixels: Minimum stroke width.
            stroked: Whether to draw stroke.
            filled: Whether to fill points.
            pickable: Whether layer responds to hover/click.
            opacity: Layer opacity.
            **kwargs: Additional layer props.
        """
        layer_id = name or f"scatterplot-{len(self._deck_layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addScatterplotLayer",
            id=layer_id,
            data=processed_data,
            getPosition=get_position,
            getRadius=get_radius,
            getFillColor=get_fill_color or [51, 136, 255, 200],
            getLineColor=get_line_color or [255, 255, 255, 255],
            radiusScale=radius_scale,
            radiusMinPixels=radius_min_pixels,
            radiusMaxPixels=radius_max_pixels,
            lineWidthMinPixels=line_width_min_pixels,
            stroked=stroked,
            filled=filled,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._deck_layers = {
            **self._deck_layers,
            layer_id: {"type": "ScatterplotLayer", "id": layer_id},
        }

    # -------------------------------------------------------------------------
    # DeckGL Arc Layer
    # -------------------------------------------------------------------------

    def add_arc_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_source_position: Union[str, Callable] = "source",
        get_target_position: Union[str, Callable] = "target",
        get_source_color: Union[List[int], str, Callable] = None,
        get_target_color: Union[List[int], str, Callable] = None,
        get_width: Union[float, str, Callable] = 1,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add an arc layer for origin-destination visualization.

        Args:
            data: Array of data objects with source/target coordinates.
            name: Layer ID.
            get_source_position: Accessor for source position [lng, lat].
            get_target_position: Accessor for target position [lng, lat].
            get_source_color: Accessor for source color [r, g, b, a].
            get_target_color: Accessor for target color [r, g, b, a].
            get_width: Accessor for arc width.
            pickable: Whether layer responds to hover/click.
            opacity: Layer opacity.
            **kwargs: Additional layer props.
        """
        layer_id = name or f"arc-{len(self._deck_layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addArcLayer",
            id=layer_id,
            data=processed_data,
            getSourcePosition=get_source_position,
            getTargetPosition=get_target_position,
            getSourceColor=get_source_color or [51, 136, 255, 255],
            getTargetColor=get_target_color or [255, 136, 51, 255],
            getWidth=get_width,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._deck_layers = {
            **self._deck_layers,
            layer_id: {"type": "ArcLayer", "id": layer_id},
        }

    # -------------------------------------------------------------------------
    # DeckGL Point Cloud Layer
    # -------------------------------------------------------------------------

    def add_point_cloud_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_position: Union[str, Callable] = "position",
        get_color: Union[List[int], str, Callable] = None,
        get_normal: Union[str, Callable] = None,
        point_size: float = 2,
        size_units: str = "pixels",
        coordinate_system: Optional[str] = None,
        coordinate_origin: Optional[List[float]] = None,
        pickable: bool = True,
        opacity: float = 1.0,
        **kwargs,
    ) -> None:
        """Add a point cloud layer for 3D point visualization.

        Renders large point cloud datasets typically from LiDAR or 3D scanning.
        Supports both 2D and 3D coordinates with optional normal vectors for
        lighting effects.

        Args:
            data: Array of point data with position [x, y, z] coordinates.
            name: Layer ID. If None, auto-generated.
            get_position: Accessor for point position [x, y, z].
            get_color: Accessor for point color [r, g, b, a].
            get_normal: Accessor for point normal [nx, ny, nz] for lighting.
            point_size: Point size in size_units.
            size_units: Units for point_size ('pixels' or 'meters').
            coordinate_system: Coordinate system ('CARTESIAN', 'METER_OFFSETS',
                'LNGLAT', 'LNGLAT_OFFSETS').
            coordinate_origin: Origin for offset coordinate systems [lng, lat, z].
            pickable: Whether layer responds to hover/click.
            opacity: Layer opacity (0-1).
            **kwargs: Additional PointCloudLayer props.

        Example:
            >>> m = DeckGLMap()
            >>> points = [
            ...     {"position": [-122.4, 37.8, 100], "color": [255, 0, 0]},
            ...     {"position": [-122.5, 37.7, 200], "color": [0, 255, 0]},
            ... ]
            >>> m.add_point_cloud_layer(
            ...     data=points,
            ...     point_size=5,
            ...     get_color="color"
            ... )
        """
        layer_id = name or f"pointcloud-{len(self._deck_layers)}"
        processed_data = self._process_deck_data(data)

        layer_kwargs = {
            "id": layer_id,
            "data": processed_data,
            "getPosition": get_position,
            "getColor": get_color or [255, 255, 255, 255],
            "pointSize": point_size,
            "sizeUnits": size_units,
            "pickable": pickable,
            "opacity": opacity,
        }

        if get_normal is not None:
            layer_kwargs["getNormal"] = get_normal

        if coordinate_system is not None:
            layer_kwargs["coordinateSystem"] = coordinate_system

        if coordinate_origin is not None:
            layer_kwargs["coordinateOrigin"] = coordinate_origin

        layer_kwargs.update(kwargs)
        self.call_js_method("addPointCloudLayer", **layer_kwargs)

        self._deck_layers = {
            **self._deck_layers,
            layer_id: {"type": "PointCloudLayer", "id": layer_id},
        }

    # -------------------------------------------------------------------------
    # DeckGL Path Layer
    # -------------------------------------------------------------------------

    def add_path_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_path: Union[str, Callable] = "path",
        get_color: Union[List[int], str, Callable] = None,
        get_width: Union[float, str, Callable] = 1,
        width_scale: float = 1,
        width_min_pixels: float = 1,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add a path layer for polyline visualization.

        Args:
            data: Array of data objects with path coordinates.
            name: Layer ID.
            get_path: Accessor for path coordinates [[lng, lat], ...].
            get_color: Accessor for path color [r, g, b, a].
            get_width: Accessor for path width.
            width_scale: Global width multiplier.
            width_min_pixels: Minimum width in pixels.
            pickable: Whether layer responds to hover/click.
            opacity: Layer opacity.
            **kwargs: Additional layer props.
        """
        layer_id = name or f"path-{len(self._deck_layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addPathLayer",
            id=layer_id,
            data=processed_data,
            getPath=get_path,
            getColor=get_color or [51, 136, 255, 200],
            getWidth=get_width,
            widthScale=width_scale,
            widthMinPixels=width_min_pixels,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._deck_layers = {
            **self._deck_layers,
            layer_id: {"type": "PathLayer", "id": layer_id},
        }

    # -------------------------------------------------------------------------
    # DeckGL Polygon Layer
    # -------------------------------------------------------------------------

    def add_polygon_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_polygon: Union[str, Callable] = "polygon",
        get_fill_color: Union[List[int], str, Callable] = None,
        get_line_color: Union[List[int], str, Callable] = None,
        get_line_width: Union[float, str, Callable] = 1,
        get_elevation: Union[float, str, Callable] = 0,
        extruded: bool = False,
        wireframe: bool = False,
        filled: bool = True,
        stroked: bool = True,
        line_width_min_pixels: float = 1,
        pickable: bool = True,
        opacity: float = 0.5,
        **kwargs,
    ) -> None:
        """Add a polygon layer for filled polygon visualization.

        Args:
            data: Array of data objects with polygon coordinates.
            name: Layer ID.
            get_polygon: Accessor for polygon coordinates.
            get_fill_color: Accessor for fill color [r, g, b, a].
            get_line_color: Accessor for stroke color [r, g, b, a].
            get_line_width: Accessor for stroke width.
            get_elevation: Accessor for 3D extrusion height.
            extruded: Whether to render as 3D polygons.
            wireframe: Whether to render wireframe (extruded only).
            filled: Whether to fill polygons.
            stroked: Whether to draw stroke.
            line_width_min_pixels: Minimum stroke width.
            pickable: Whether layer responds to hover/click.
            opacity: Layer opacity.
            **kwargs: Additional layer props.
        """
        layer_id = name or f"polygon-{len(self._deck_layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addPolygonLayer",
            id=layer_id,
            data=processed_data,
            getPolygon=get_polygon,
            getFillColor=get_fill_color or [51, 136, 255, 128],
            getLineColor=get_line_color or [0, 0, 255, 255],
            getLineWidth=get_line_width,
            getElevation=get_elevation,
            extruded=extruded,
            wireframe=wireframe,
            filled=filled,
            stroked=stroked,
            lineWidthMinPixels=line_width_min_pixels,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._deck_layers = {
            **self._deck_layers,
            layer_id: {"type": "PolygonLayer", "id": layer_id},
        }

    # -------------------------------------------------------------------------
    # DeckGL Hexagon Layer
    # -------------------------------------------------------------------------

    def add_hexagon_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_position: Union[str, Callable] = "coordinates",
        radius: float = 1000,
        elevation_scale: float = 4,
        extruded: bool = True,
        color_range: Optional[List[List[int]]] = None,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add a hexagon layer for hexbin aggregation visualization.

        Args:
            data: Array of data objects with position coordinates.
            name: Layer ID.
            get_position: Accessor for point position [lng, lat].
            radius: Hexagon radius in meters.
            elevation_scale: Elevation multiplier for 3D.
            extruded: Whether to render as 3D hexagons.
            color_range: Color gradient for aggregation [[r, g, b], ...].
            pickable: Whether layer responds to hover/click.
            opacity: Layer opacity.
            **kwargs: Additional layer props.
        """
        layer_id = name or f"hexagon-{len(self._deck_layers)}"
        processed_data = self._process_deck_data(data)

        default_color_range = [
            [1, 152, 189],
            [73, 227, 206],
            [216, 254, 181],
            [254, 237, 177],
            [254, 173, 84],
            [209, 55, 78],
        ]

        self.call_js_method(
            "addHexagonLayer",
            id=layer_id,
            data=processed_data,
            getPosition=get_position,
            radius=radius,
            elevationScale=elevation_scale,
            extruded=extruded,
            colorRange=color_range or default_color_range,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._deck_layers = {
            **self._deck_layers,
            layer_id: {"type": "HexagonLayer", "id": layer_id},
        }

    # -------------------------------------------------------------------------
    # DeckGL Heatmap Layer
    # -------------------------------------------------------------------------

    def add_heatmap_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_position: Union[str, Callable] = "coordinates",
        get_weight: Union[float, str, Callable] = 1,
        radius_pixels: float = 30,
        intensity: float = 1,
        threshold: float = 0.05,
        color_range: Optional[List[List[int]]] = None,
        opacity: float = 1,
        **kwargs,
    ) -> None:
        """Add a heatmap layer for density visualization.

        Args:
            data: Array of data objects with position coordinates.
            name: Layer ID.
            get_position: Accessor for point position [lng, lat].
            get_weight: Accessor for point weight.
            radius_pixels: Influence radius in pixels.
            intensity: Intensity multiplier.
            threshold: Minimum density threshold.
            color_range: Color gradient [[r, g, b, a], ...].
            opacity: Layer opacity.
            **kwargs: Additional layer props.
        """
        layer_id = name or f"heatmap-{len(self._deck_layers)}"
        processed_data = self._process_deck_data(data)

        default_color_range = [
            [255, 255, 178, 25],
            [254, 217, 118, 85],
            [254, 178, 76, 127],
            [253, 141, 60, 170],
            [240, 59, 32, 212],
            [189, 0, 38, 255],
        ]

        self.call_js_method(
            "addHeatmapLayer",
            id=layer_id,
            data=processed_data,
            getPosition=get_position,
            getWeight=get_weight,
            radiusPixels=radius_pixels,
            intensity=intensity,
            threshold=threshold,
            colorRange=color_range or default_color_range,
            opacity=opacity,
            **kwargs,
        )

        self._deck_layers = {
            **self._deck_layers,
            layer_id: {"type": "HeatmapLayer", "id": layer_id},
        }

    # -------------------------------------------------------------------------
    # DeckGL Grid Layer
    # -------------------------------------------------------------------------

    def add_grid_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_position: Union[str, Callable] = "coordinates",
        cell_size: float = 200,
        elevation_scale: float = 4,
        extruded: bool = True,
        color_range: Optional[List[List[int]]] = None,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add a grid layer for square grid aggregation visualization.

        Args:
            data: Array of data objects with position coordinates.
            name: Layer ID.
            get_position: Accessor for point position [lng, lat].
            cell_size: Grid cell size in meters.
            elevation_scale: Elevation multiplier for 3D.
            extruded: Whether to render as 3D cells.
            color_range: Color gradient [[r, g, b], ...].
            pickable: Whether layer responds to hover/click.
            opacity: Layer opacity.
            **kwargs: Additional layer props.
        """
        layer_id = name or f"grid-{len(self._deck_layers)}"
        processed_data = self._process_deck_data(data)

        default_color_range = [
            [1, 152, 189],
            [73, 227, 206],
            [216, 254, 181],
            [254, 237, 177],
            [254, 173, 84],
            [209, 55, 78],
        ]

        self.call_js_method(
            "addGridLayer",
            id=layer_id,
            data=processed_data,
            getPosition=get_position,
            cellSize=cell_size,
            elevationScale=elevation_scale,
            extruded=extruded,
            colorRange=color_range or default_color_range,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._deck_layers = {
            **self._deck_layers,
            layer_id: {"type": "GridLayer", "id": layer_id},
        }

    # -------------------------------------------------------------------------
    # DeckGL Icon Layer
    # -------------------------------------------------------------------------

    def add_icon_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_position: Union[str, Callable] = "coordinates",
        get_icon: Union[str, Callable] = "icon",
        get_size: Union[float, str, Callable] = 20,
        get_color: Union[List[int], str, Callable] = None,
        icon_atlas: Optional[str] = None,
        icon_mapping: Optional[Dict] = None,
        pickable: bool = True,
        opacity: float = 1,
        **kwargs,
    ) -> None:
        """Add an icon layer for custom marker visualization.

        Args:
            data: Array of data objects with position coordinates.
            name: Layer ID.
            get_position: Accessor for icon position [lng, lat].
            get_icon: Accessor for icon name in icon_mapping.
            get_size: Accessor for icon size.
            get_color: Accessor for icon tint color [r, g, b, a].
            icon_atlas: URL to icon atlas image.
            icon_mapping: Dict mapping icon names to atlas coordinates.
            pickable: Whether layer responds to hover/click.
            opacity: Layer opacity.
            **kwargs: Additional layer props.
        """
        layer_id = name or f"icon-{len(self._deck_layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addIconLayer",
            id=layer_id,
            data=processed_data,
            getPosition=get_position,
            getIcon=get_icon,
            getSize=get_size,
            getColor=get_color or [255, 255, 255, 255],
            iconAtlas=icon_atlas,
            iconMapping=icon_mapping,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._deck_layers = {
            **self._deck_layers,
            layer_id: {"type": "IconLayer", "id": layer_id},
        }

    # -------------------------------------------------------------------------
    # DeckGL Text Layer
    # -------------------------------------------------------------------------

    def add_text_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_position: Union[str, Callable] = "coordinates",
        get_text: Union[str, Callable] = "text",
        get_size: Union[float, str, Callable] = 12,
        get_color: Union[List[int], str, Callable] = None,
        get_angle: Union[float, str, Callable] = 0,
        text_anchor: str = "middle",
        alignment_baseline: str = "center",
        pickable: bool = True,
        opacity: float = 1,
        **kwargs,
    ) -> None:
        """Add a text layer for label visualization.

        Args:
            data: Array of data objects with position and text.
            name: Layer ID.
            get_position: Accessor for text position [lng, lat].
            get_text: Accessor for text content.
            get_size: Accessor for text size.
            get_color: Accessor for text color [r, g, b, a].
            get_angle: Accessor for text rotation in degrees.
            text_anchor: Horizontal alignment ('start', 'middle', 'end').
            alignment_baseline: Vertical alignment ('top', 'center', 'bottom').
            pickable: Whether layer responds to hover/click.
            opacity: Layer opacity.
            **kwargs: Additional layer props.
        """
        layer_id = name or f"text-{len(self._deck_layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addTextLayer",
            id=layer_id,
            data=processed_data,
            getPosition=get_position,
            getText=get_text,
            getSize=get_size,
            getColor=get_color or [0, 0, 0, 255],
            getAngle=get_angle,
            getTextAnchor=text_anchor,
            getAlignmentBaseline=alignment_baseline,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._deck_layers = {
            **self._deck_layers,
            layer_id: {"type": "TextLayer", "id": layer_id},
        }

    # -------------------------------------------------------------------------
    # DeckGL GeoJSON Layer
    # -------------------------------------------------------------------------

    def add_geojson_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_fill_color: Union[List[int], str, Callable] = None,
        get_line_color: Union[List[int], str, Callable] = None,
        get_line_width: Union[float, str, Callable] = 1,
        get_point_radius: Union[float, str, Callable] = 5,
        get_elevation: Union[float, str, Callable] = 0,
        extruded: bool = False,
        wireframe: bool = False,
        filled: bool = True,
        stroked: bool = True,
        line_width_min_pixels: float = 1,
        point_radius_min_pixels: float = 2,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add a GeoJSON layer for rendering GeoJSON features.

        Args:
            data: GeoJSON object or URL.
            name: Layer ID.
            get_fill_color: Accessor for fill color [r, g, b, a].
            get_line_color: Accessor for stroke color [r, g, b, a].
            get_line_width: Accessor for stroke width.
            get_point_radius: Accessor for point radius.
            get_elevation: Accessor for 3D extrusion height.
            extruded: Whether to render as 3D features.
            wireframe: Whether to render wireframe (extruded only).
            filled: Whether to fill features.
            stroked: Whether to draw stroke.
            line_width_min_pixels: Minimum stroke width.
            point_radius_min_pixels: Minimum point radius.
            pickable: Whether layer responds to hover/click.
            opacity: Layer opacity.
            **kwargs: Additional layer props.
        """
        layer_id = name or f"geojson-{len(self._deck_layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addGeoJsonLayer",
            id=layer_id,
            data=processed_data,
            getFillColor=get_fill_color or [51, 136, 255, 128],
            getLineColor=get_line_color or [0, 0, 0, 255],
            getLineWidth=get_line_width,
            getPointRadius=get_point_radius,
            getElevation=get_elevation,
            extruded=extruded,
            wireframe=wireframe,
            filled=filled,
            stroked=stroked,
            lineWidthMinPixels=line_width_min_pixels,
            pointRadiusMinPixels=point_radius_min_pixels,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._deck_layers = {
            **self._deck_layers,
            layer_id: {"type": "GeoJsonLayer", "id": layer_id},
        }

    # -------------------------------------------------------------------------
    # DeckGL Contour Layer
    # -------------------------------------------------------------------------

    def add_contour_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_position: Union[str, Callable] = "coordinates",
        get_weight: Union[float, str, Callable] = 1,
        cell_size: float = 200,
        contours: Optional[List[Dict]] = None,
        pickable: bool = True,
        opacity: float = 1,
        **kwargs,
    ) -> None:
        """Add a contour layer for isoline visualization.

        Args:
            data: Array of data objects with position coordinates.
            name: Layer ID.
            get_position: Accessor for point position [lng, lat].
            get_weight: Accessor for point weight.
            cell_size: Grid cell size for aggregation.
            contours: Contour definitions [{threshold, color, strokeWidth}, ...].
            pickable: Whether layer responds to hover/click.
            opacity: Layer opacity.
            **kwargs: Additional layer props.
        """
        layer_id = name or f"contour-{len(self._deck_layers)}"
        processed_data = self._process_deck_data(data)

        default_contours = [
            {"threshold": 1, "color": [255, 255, 255], "strokeWidth": 1},
            {"threshold": 5, "color": [51, 136, 255], "strokeWidth": 2},
            {"threshold": 10, "color": [0, 0, 255], "strokeWidth": 3},
        ]

        self.call_js_method(
            "addContourLayer",
            id=layer_id,
            data=processed_data,
            getPosition=get_position,
            getWeight=get_weight,
            cellSize=cell_size,
            contours=contours or default_contours,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._deck_layers = {
            **self._deck_layers,
            layer_id: {"type": "ContourLayer", "id": layer_id},
        }

    # -------------------------------------------------------------------------
    # DeckGL Screen Grid Layer
    # -------------------------------------------------------------------------

    def add_screen_grid_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_position: Union[str, Callable] = "coordinates",
        get_weight: Union[float, str, Callable] = 1,
        cell_size_pixels: float = 50,
        color_range: Optional[List[List[int]]] = None,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add a screen grid layer for screen-space grid aggregation.

        Args:
            data: Array of data objects with position coordinates.
            name: Layer ID.
            get_position: Accessor for point position [lng, lat].
            get_weight: Accessor for point weight.
            cell_size_pixels: Grid cell size in pixels.
            color_range: Color gradient [[r, g, b, a], ...].
            pickable: Whether layer responds to hover/click.
            opacity: Layer opacity.
            **kwargs: Additional layer props.
        """
        layer_id = name or f"screengrid-{len(self._deck_layers)}"
        processed_data = self._process_deck_data(data)

        default_color_range = [
            [255, 255, 178, 25],
            [254, 217, 118, 85],
            [254, 178, 76, 127],
            [253, 141, 60, 170],
            [240, 59, 32, 212],
            [189, 0, 38, 255],
        ]

        self.call_js_method(
            "addScreenGridLayer",
            id=layer_id,
            data=processed_data,
            getPosition=get_position,
            getWeight=get_weight,
            cellSizePixels=cell_size_pixels,
            colorRange=color_range or default_color_range,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._deck_layers = {
            **self._deck_layers,
            layer_id: {"type": "ScreenGridLayer", "id": layer_id},
        }

    # -------------------------------------------------------------------------
    # Generic DeckGL Layer
    # -------------------------------------------------------------------------

    def add_deckgl_layer(
        self,
        layer_type: str,
        data: Any,
        name: Optional[str] = None,
        **kwargs,
    ) -> None:
        """Add a generic deck.gl layer to the map.

        This method provides a flexible way to add any supported deck.gl layer
        type using a single interface. For commonly used layers, prefer the
        specific methods (e.g., add_scatterplot_layer) for better IDE support.

        Args:
            layer_type: The deck.gl layer type. Supported types include:
                'ScatterplotLayer', 'ArcLayer', 'PathLayer', 'PolygonLayer',
                'HexagonLayer', 'HeatmapLayer', 'GridLayer', 'IconLayer',
                'TextLayer', 'GeoJsonLayer', 'ContourLayer', 'ScreenGridLayer',
                'PointCloudLayer', 'TripsLayer', 'LineLayer'.
            data: Array of data objects or GeoJSON.
            name: Layer ID. If None, auto-generated from layer_type.
            **kwargs: Layer-specific properties passed directly to deck.gl.
                Common properties include:
                - opacity: Layer opacity (0-1)
                - pickable: Whether layer responds to hover/click
                - getPosition: Accessor for position coordinates
                - getColor/getFillColor/getLineColor: Color accessors

        Example:
            >>> m = DeckGLMap()
            >>> # Add a TripsLayer with animation
            >>> m.add_deckgl_layer(
            ...     'TripsLayer',
            ...     data=trips_data,
            ...     getPath='waypoints',
            ...     getTimestamps='timestamps',
            ...     getColor=[253, 128, 93],
            ...     trailLength=180,
            ... )
            >>> # Add a LineLayer
            >>> m.add_deckgl_layer(
            ...     'LineLayer',
            ...     data=lines_data,
            ...     getSourcePosition='source',
            ...     getTargetPosition='target',
            ...     getColor=[0, 128, 255],
            ... )
        """
        # Normalize layer type and create prefix
        layer_type_clean = layer_type.replace("Layer", "")
        prefix = layer_type_clean.lower()
        layer_id = name or f"{prefix}-{len(self._deck_layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addDeckGLLayer",
            layerType=layer_type,
            id=layer_id,
            data=processed_data,
            **kwargs,
        )

        self._deck_layers = {
            **self._deck_layers,
            layer_id: {"type": layer_type, "id": layer_id},
        }

    # -------------------------------------------------------------------------
    # DeckGL Trips Layer
    # -------------------------------------------------------------------------

    def add_trips_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_path: Union[str, Callable] = "waypoints",
        get_timestamps: Union[str, Callable] = "timestamps",
        get_color: Union[List[int], str, Callable] = None,
        width_min_pixels: float = 2,
        trail_length: float = 180,
        current_time: float = 0,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add a trips layer for animated path visualization.

        The TripsLayer renders animated paths showing movement over time,
        ideal for visualizing vehicle routes, migration patterns, or any
        time-based trajectory data.

        Args:
            data: Array of trip objects with waypoints and timestamps.
            name: Layer ID. If None, auto-generated.
            get_path: Accessor for waypoint coordinates [[lng, lat], ...].
            get_timestamps: Accessor for timestamps at each waypoint.
            get_color: Accessor for trip color [r, g, b] or [r, g, b, a].
            width_min_pixels: Minimum trail width in pixels.
            trail_length: Trail length in timestamp units.
            current_time: Current animation time.
            pickable: Whether layer responds to hover/click.
            opacity: Layer opacity (0-1).
            **kwargs: Additional TripsLayer props.

        Example:
            >>> m = DeckGLMap()
            >>> trips = [
            ...     {
            ...         "waypoints": [[-122.4, 37.8], [-122.5, 37.7], [-122.6, 37.8]],
            ...         "timestamps": [0, 50, 100]
            ...     }
            ... ]
            >>> m.add_trips_layer(
            ...     data=trips,
            ...     trail_length=180,
            ...     current_time=50,
            ... )
        """
        layer_id = name or f"trips-{len(self._deck_layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addTripsLayer",
            id=layer_id,
            data=processed_data,
            getPath=get_path,
            getTimestamps=get_timestamps,
            getColor=get_color or [253, 128, 93],
            widthMinPixels=width_min_pixels,
            trailLength=trail_length,
            currentTime=current_time,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._deck_layers = {
            **self._deck_layers,
            layer_id: {"type": "TripsLayer", "id": layer_id},
        }

    # -------------------------------------------------------------------------
    # DeckGL Line Layer
    # -------------------------------------------------------------------------

    def add_line_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_source_position: Union[str, Callable] = "sourcePosition",
        get_target_position: Union[str, Callable] = "targetPosition",
        get_color: Union[List[int], str, Callable] = None,
        get_width: Union[float, str, Callable] = 1,
        width_min_pixels: float = 1,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add a line layer for simple line segment visualization.

        The LineLayer renders straight line segments between source and
        target positions. Unlike ArcLayer, lines are drawn directly
        without curvature.

        Args:
            data: Array of line objects with source/target positions.
            name: Layer ID. If None, auto-generated.
            get_source_position: Accessor for source position [lng, lat].
            get_target_position: Accessor for target position [lng, lat].
            get_color: Accessor for line color [r, g, b] or [r, g, b, a].
            get_width: Accessor for line width.
            width_min_pixels: Minimum line width in pixels.
            pickable: Whether layer responds to hover/click.
            opacity: Layer opacity (0-1).
            **kwargs: Additional LineLayer props.

        Example:
            >>> m = DeckGLMap()
            >>> lines = [
            ...     {"sourcePosition": [-122.4, 37.8], "targetPosition": [-122.5, 37.7]},
            ...     {"sourcePosition": [-122.5, 37.7], "targetPosition": [-122.6, 37.8]},
            ... ]
            >>> m.add_line_layer(
            ...     data=lines,
            ...     get_color=[0, 128, 255],
            ...     get_width=2,
            ... )
        """
        layer_id = name or f"line-{len(self._deck_layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addLineLayer",
            id=layer_id,
            data=processed_data,
            getSourcePosition=get_source_position,
            getTargetPosition=get_target_position,
            getColor=get_color or [51, 136, 255, 200],
            getWidth=get_width,
            widthMinPixels=width_min_pixels,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._deck_layers = {
            **self._deck_layers,
            layer_id: {"type": "LineLayer", "id": layer_id},
        }

    # -------------------------------------------------------------------------
    # DeckGL COG Layer
    # -------------------------------------------------------------------------

    def add_cog_layer(
        self,
        url: str,
        name: Optional[str] = None,
        opacity: float = 1.0,
        visible: bool = True,
        debug: bool = False,
        debug_opacity: float = 0.25,
        max_error: float = 0.125,
        fit_bounds: bool = True,
        before_id: Optional[str] = None,
        **kwargs,
    ) -> None:
        """Add a Cloud Optimized GeoTIFF (COG) layer using @developmentseed/deck.gl-geotiff.

        This method renders COG files directly in the browser using GPU-accelerated
        deck.gl rendering with automatic reprojection support.

        Args:
            url: URL to the Cloud Optimized GeoTIFF file.
            name: Layer ID. If None, auto-generated.
            opacity: Layer opacity (0-1).
            visible: Whether layer is visible.
            debug: Show reprojection mesh for debugging.
            debug_opacity: Opacity of debug mesh (0-1).
            max_error: Maximum reprojection error in pixels. Lower values
                create denser mesh for better accuracy.
            fit_bounds: Whether to fit map to COG bounds after loading.
            before_id: ID of layer to insert before.
            **kwargs: Additional COGLayer props.

        Example:
            >>> m = DeckGLMap()
            >>> m.add_cog_layer(
            ...     "https://example.com/landcover.tif",
            ...     name="landcover",
            ...     opacity=0.8
            ... )
        """
        # Use a monotonically increasing counter to avoid ID collisions when layers are removed.
        counter = getattr(self, "_cog_layer_counter", 0)
        layer_id = name or f"cog-{counter}"
        self._cog_layer_counter = counter + 1

        self.call_js_method(
            "addCOGLayer",
            id=layer_id,
            geotiff=url,
            opacity=opacity,
            visible=visible,
            debug=debug,
            debugOpacity=debug_opacity,
            maxError=max_error,
            fitBounds=fit_bounds,
            beforeId=before_id,
            **kwargs,
        )

        self._deck_layers = {
            **self._deck_layers,
            layer_id: {"type": "COGLayer", "id": layer_id, "url": url},
        }

    # -------------------------------------------------------------------------
    # New DeckGL Layer Types
    # -------------------------------------------------------------------------

    def add_bitmap_layer(
        self,
        image: str,
        bounds: List[float],
        name: Optional[str] = None,
        opacity: float = 1.0,
        visible: bool = True,
        pickable: bool = False,
        desaturate: float = 0,
        transparent_color: Optional[List[int]] = None,
        tint_color: Optional[List[int]] = None,
        **kwargs,
    ) -> None:
        """Add a bitmap layer for raster image overlay.

        Args:
            image: URL or data URI of the image.
            bounds: Bounding box [west, south, east, north].
            name: Layer ID.
            opacity: Layer opacity (0-1).
            visible: Whether layer is visible.
            pickable: Whether layer responds to hover/click.
            desaturate: Desaturation amount (0-1).
            transparent_color: Color to make transparent [r, g, b, a].
            tint_color: Color to tint the image [r, g, b].
            **kwargs: Additional BitmapLayer props.
        """
        layer_id = name or f"bitmap-{len(self._deck_layers)}"

        self.call_js_method(
            "addBitmapLayer",
            id=layer_id,
            image=image,
            bounds=bounds,
            opacity=opacity,
            visible=visible,
            pickable=pickable,
            desaturate=desaturate,
            transparentColor=transparent_color or [0, 0, 0, 0],
            tintColor=tint_color or [255, 255, 255],
            **kwargs,
        )

        self._deck_layers = {
            **self._deck_layers,
            layer_id: {"type": "BitmapLayer", "id": layer_id},
        }

    def add_column_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_position: Union[str, Callable] = "coordinates",
        get_fill_color: Union[List[int], str, Callable] = None,
        get_line_color: Union[List[int], str, Callable] = None,
        get_elevation: Union[float, str, Callable] = 1000,
        radius: float = 1000,
        disk_resolution: int = 20,
        elevation_scale: float = 1,
        coverage: float = 1,
        extruded: bool = True,
        filled: bool = True,
        stroked: bool = False,
        wireframe: bool = False,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add a column layer for 3D column/bar visualization.

        Args:
            data: Array of data objects with position coordinates.
            name: Layer ID.
            get_position: Accessor for column position [lng, lat].
            get_fill_color: Accessor for fill color [r, g, b, a].
            get_line_color: Accessor for stroke color [r, g, b, a].
            get_elevation: Accessor for column height.
            radius: Column radius in meters.
            disk_resolution: Number of sides for column polygon.
            elevation_scale: Elevation multiplier.
            coverage: Column coverage (0-1).
            extruded: Whether to extrude columns.
            filled: Whether to fill columns.
            stroked: Whether to stroke columns.
            wireframe: Whether to render as wireframe.
            pickable: Whether layer responds to hover/click.
            opacity: Layer opacity.
            **kwargs: Additional ColumnLayer props.
        """
        layer_id = name or f"column-{len(self._deck_layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addColumnLayer",
            id=layer_id,
            data=processed_data,
            getPosition=get_position,
            getFillColor=get_fill_color or [255, 140, 0, 200],
            getLineColor=get_line_color or [0, 0, 0, 255],
            getElevation=get_elevation,
            radius=radius,
            diskResolution=disk_resolution,
            elevationScale=elevation_scale,
            coverage=coverage,
            extruded=extruded,
            filled=filled,
            stroked=stroked,
            wireframe=wireframe,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._deck_layers = {
            **self._deck_layers,
            layer_id: {"type": "ColumnLayer", "id": layer_id},
        }

    def add_grid_cell_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_position: Union[str, Callable] = "coordinates",
        get_color: Union[List[int], str, Callable] = None,
        get_elevation: Union[float, str, Callable] = 1000,
        cell_size: float = 200,
        coverage: float = 1,
        elevation_scale: float = 1,
        extruded: bool = True,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add a grid cell layer for pre-aggregated grid visualization.

        Args:
            data: Array of data objects with position coordinates.
            name: Layer ID.
            get_position: Accessor for cell position [lng, lat].
            get_color: Accessor for cell color [r, g, b, a].
            get_elevation: Accessor for cell height.
            cell_size: Cell size in meters.
            coverage: Cell coverage (0-1).
            elevation_scale: Elevation multiplier.
            extruded: Whether to extrude cells.
            pickable: Whether layer responds to hover/click.
            opacity: Layer opacity.
            **kwargs: Additional GridCellLayer props.
        """
        layer_id = name or f"gridcell-{len(self._deck_layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addGridCellLayer",
            id=layer_id,
            data=processed_data,
            getPosition=get_position,
            getColor=get_color or [255, 140, 0, 200],
            getElevation=get_elevation,
            cellSize=cell_size,
            coverage=coverage,
            elevationScale=elevation_scale,
            extruded=extruded,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._deck_layers = {
            **self._deck_layers,
            layer_id: {"type": "GridCellLayer", "id": layer_id},
        }

    def add_solid_polygon_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_polygon: Union[str, Callable] = "polygon",
        get_fill_color: Union[List[int], str, Callable] = None,
        get_line_color: Union[List[int], str, Callable] = None,
        get_elevation: Union[float, str, Callable] = 0,
        filled: bool = True,
        extruded: bool = False,
        wireframe: bool = False,
        elevation_scale: float = 1,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add a solid polygon layer for filled polygon visualization.

        Args:
            data: Array of data objects with polygon coordinates.
            name: Layer ID.
            get_polygon: Accessor for polygon coordinates.
            get_fill_color: Accessor for fill color [r, g, b, a].
            get_line_color: Accessor for stroke color [r, g, b, a].
            get_elevation: Accessor for 3D extrusion height.
            filled: Whether to fill polygons.
            extruded: Whether to render as 3D polygons.
            wireframe: Whether to render wireframe.
            elevation_scale: Elevation multiplier.
            pickable: Whether layer responds to hover/click.
            opacity: Layer opacity.
            **kwargs: Additional SolidPolygonLayer props.
        """
        layer_id = name or f"solidpolygon-{len(self._deck_layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addSolidPolygonLayer",
            id=layer_id,
            data=processed_data,
            getPolygon=get_polygon,
            getFillColor=get_fill_color or [51, 136, 255, 128],
            getLineColor=get_line_color or [0, 0, 0, 255],
            getElevation=get_elevation,
            filled=filled,
            extruded=extruded,
            wireframe=wireframe,
            elevationScale=elevation_scale,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._deck_layers = {
            **self._deck_layers,
            layer_id: {"type": "SolidPolygonLayer", "id": layer_id},
        }

    def add_tile_layer(
        self,
        data: Union[str, List[str]],
        name: Optional[str] = None,
        min_zoom: int = 0,
        max_zoom: int = 19,
        tile_size: int = 256,
        pickable: bool = False,
        visible: bool = True,
        opacity: float = 1.0,
        **kwargs,
    ) -> None:
        """Add a tile layer for raster tile visualization.

        Args:
            data: Tile URL template with {z}/{x}/{y} placeholders.
            name: Layer ID.
            min_zoom: Minimum zoom level.
            max_zoom: Maximum zoom level.
            tile_size: Tile size in pixels.
            pickable: Whether layer responds to hover/click.
            visible: Whether layer is visible.
            opacity: Layer opacity (0-1).
            **kwargs: Additional TileLayer props.
        """
        layer_id = name or f"tile-{len(self._deck_layers)}"

        self.call_js_method(
            "addTileLayer",
            id=layer_id,
            data=data,
            minZoom=min_zoom,
            maxZoom=max_zoom,
            tileSize=tile_size,
            pickable=pickable,
            visible=visible,
            opacity=opacity,
            **kwargs,
        )

        self._deck_layers = {
            **self._deck_layers,
            layer_id: {"type": "TileLayer", "id": layer_id},
        }

    def add_mvt_layer(
        self,
        data: Union[str, List[str]],
        name: Optional[str] = None,
        min_zoom: int = 0,
        max_zoom: int = 14,
        binary: bool = True,
        get_fill_color: Union[List[int], str, Callable] = None,
        get_line_color: Union[List[int], str, Callable] = None,
        get_line_width: Union[float, str, Callable] = 1,
        get_point_radius: Union[float, str, Callable] = 5,
        line_width_min_pixels: float = 1,
        point_radius_min_pixels: float = 2,
        pickable: bool = True,
        visible: bool = True,
        opacity: float = 1.0,
        **kwargs,
    ) -> None:
        """Add a Mapbox Vector Tile (MVT) layer.

        Args:
            data: MVT tile URL template with {z}/{x}/{y} placeholders.
            name: Layer ID.
            min_zoom: Minimum zoom level.
            max_zoom: Maximum zoom level.
            binary: Whether to use binary format.
            get_fill_color: Accessor for fill color [r, g, b, a].
            get_line_color: Accessor for stroke color [r, g, b, a].
            get_line_width: Accessor for line width.
            get_point_radius: Accessor for point radius.
            line_width_min_pixels: Minimum line width in pixels.
            point_radius_min_pixels: Minimum point radius in pixels.
            pickable: Whether layer responds to hover/click.
            visible: Whether layer is visible.
            opacity: Layer opacity (0-1).
            **kwargs: Additional MVTLayer props.
        """
        layer_id = name or f"mvt-{len(self._deck_layers)}"

        self.call_js_method(
            "addMVTLayer",
            id=layer_id,
            data=data,
            minZoom=min_zoom,
            maxZoom=max_zoom,
            binary=binary,
            getFillColor=get_fill_color or [51, 136, 255, 128],
            getLineColor=get_line_color or [0, 0, 0, 255],
            getLineWidth=get_line_width,
            getPointRadius=get_point_radius,
            lineWidthMinPixels=line_width_min_pixels,
            pointRadiusMinPixels=point_radius_min_pixels,
            pickable=pickable,
            visible=visible,
            opacity=opacity,
            **kwargs,
        )

        self._deck_layers = {
            **self._deck_layers,
            layer_id: {"type": "MVTLayer", "id": layer_id},
        }

    def add_tile3d_layer(
        self,
        data: str,
        name: Optional[str] = None,
        point_size: float = 1,
        pickable: bool = True,
        visible: bool = True,
        opacity: float = 1.0,
        load_options: Optional[Dict] = None,
        **kwargs,
    ) -> None:
        """Add a 3D Tiles layer for 3D building/terrain visualization.

        Args:
            data: URL to tileset.json.
            name: Layer ID.
            point_size: Point size for point cloud tiles.
            pickable: Whether layer responds to hover/click.
            visible: Whether layer is visible.
            opacity: Layer opacity (0-1).
            load_options: Loader options for tile loading.
            **kwargs: Additional Tile3DLayer props.
        """
        layer_id = name or f"tile3d-{len(self._deck_layers)}"

        self.call_js_method(
            "addTile3DLayer",
            id=layer_id,
            data=data,
            pointSize=point_size,
            pickable=pickable,
            visible=visible,
            opacity=opacity,
            loadOptions=load_options or {},
            **kwargs,
        )

        self._deck_layers = {
            **self._deck_layers,
            layer_id: {"type": "Tile3DLayer", "id": layer_id},
        }

    def add_terrain_layer(
        self,
        elevation_data: Union[str, List[str]],
        name: Optional[str] = None,
        texture: Optional[str] = None,
        mesh_max_error: float = 4.0,
        bounds: Optional[List[float]] = None,
        elevation_decoder: Optional[Dict] = None,
        pickable: bool = False,
        visible: bool = True,
        opacity: float = 1.0,
        wireframe: bool = False,
        **kwargs,
    ) -> None:
        """Add a terrain layer for 3D terrain visualization.

        Args:
            elevation_data: URL to elevation tiles (e.g., Mapbox terrain).
            name: Layer ID.
            texture: URL to texture tiles for terrain surface.
            mesh_max_error: Maximum mesh error in meters.
            bounds: Bounding box [west, south, east, north].
            elevation_decoder: Decoder for elevation data format.
            pickable: Whether layer responds to hover/click.
            visible: Whether layer is visible.
            opacity: Layer opacity (0-1).
            wireframe: Whether to render as wireframe.
            **kwargs: Additional TerrainLayer props.
        """
        layer_id = name or f"terrain-{len(self._deck_layers)}"

        default_decoder = {
            "rScaler": 256,
            "gScaler": 1,
            "bScaler": 1 / 256,
            "offset": -32768,
        }

        self.call_js_method(
            "addTerrainLayer",
            id=layer_id,
            elevationData=elevation_data,
            texture=texture,
            meshMaxError=mesh_max_error,
            bounds=bounds,
            elevationDecoder=elevation_decoder or default_decoder,
            pickable=pickable,
            visible=visible,
            opacity=opacity,
            wireframe=wireframe,
            **kwargs,
        )

        self._deck_layers = {
            **self._deck_layers,
            layer_id: {"type": "TerrainLayer", "id": layer_id},
        }

    def add_great_circle_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_source_position: Union[str, Callable] = "source",
        get_target_position: Union[str, Callable] = "target",
        get_source_color: Union[List[int], str, Callable] = None,
        get_target_color: Union[List[int], str, Callable] = None,
        get_width: Union[float, str, Callable] = 1,
        width_min_pixels: float = 1,
        width_max_pixels: float = 100,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add a great circle layer for geodesic arc visualization.

        Args:
            data: Array of data objects with source/target coordinates.
            name: Layer ID.
            get_source_position: Accessor for source position [lng, lat].
            get_target_position: Accessor for target position [lng, lat].
            get_source_color: Accessor for source color [r, g, b, a].
            get_target_color: Accessor for target color [r, g, b, a].
            get_width: Accessor for line width.
            width_min_pixels: Minimum line width in pixels.
            width_max_pixels: Maximum line width in pixels.
            pickable: Whether layer responds to hover/click.
            opacity: Layer opacity.
            **kwargs: Additional GreatCircleLayer props.
        """
        layer_id = name or f"greatcircle-{len(self._deck_layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addGreatCircleLayer",
            id=layer_id,
            data=processed_data,
            getSourcePosition=get_source_position,
            getTargetPosition=get_target_position,
            getSourceColor=get_source_color or [51, 136, 255, 255],
            getTargetColor=get_target_color or [255, 136, 51, 255],
            getWidth=get_width,
            widthMinPixels=width_min_pixels,
            widthMaxPixels=width_max_pixels,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._deck_layers = {
            **self._deck_layers,
            layer_id: {"type": "GreatCircleLayer", "id": layer_id},
        }

    def add_h3_hexagon_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_hexagon: Union[str, Callable] = "hexagon",
        get_fill_color: Union[List[int], str, Callable] = None,
        get_line_color: Union[List[int], str, Callable] = None,
        get_elevation: Union[float, str, Callable] = 0,
        filled: bool = True,
        stroked: bool = True,
        extruded: bool = False,
        wireframe: bool = False,
        elevation_scale: float = 1,
        coverage: float = 1,
        high_precision: bool = False,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add an H3 hexagon layer for H3 spatial index visualization.

        Args:
            data: Array of data objects with H3 index.
            name: Layer ID.
            get_hexagon: Accessor for H3 index string.
            get_fill_color: Accessor for fill color [r, g, b, a].
            get_line_color: Accessor for stroke color [r, g, b, a].
            get_elevation: Accessor for 3D extrusion height.
            filled: Whether to fill hexagons.
            stroked: Whether to stroke hexagons.
            extruded: Whether to render as 3D hexagons.
            wireframe: Whether to render wireframe.
            elevation_scale: Elevation multiplier.
            coverage: Hexagon coverage (0-1).
            high_precision: Use high precision rendering.
            pickable: Whether layer responds to hover/click.
            opacity: Layer opacity.
            **kwargs: Additional H3HexagonLayer props.
        """
        layer_id = name or f"h3hexagon-{len(self._deck_layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addH3HexagonLayer",
            id=layer_id,
            data=processed_data,
            getHexagon=get_hexagon,
            getFillColor=get_fill_color or [51, 136, 255, 128],
            getLineColor=get_line_color or [0, 0, 0, 255],
            getElevation=get_elevation,
            filled=filled,
            stroked=stroked,
            extruded=extruded,
            wireframe=wireframe,
            elevationScale=elevation_scale,
            coverage=coverage,
            highPrecision=high_precision,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._deck_layers = {
            **self._deck_layers,
            layer_id: {"type": "H3HexagonLayer", "id": layer_id},
        }

    def add_h3_cluster_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_hexagons: Union[str, Callable] = "hexagons",
        get_fill_color: Union[List[int], str, Callable] = None,
        get_line_color: Union[List[int], str, Callable] = None,
        get_line_width: Union[float, str, Callable] = 1,
        filled: bool = True,
        stroked: bool = True,
        extruded: bool = False,
        elevation_scale: float = 1,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add an H3 cluster layer for grouped H3 cell visualization.

        Args:
            data: Array of data objects with H3 index arrays.
            name: Layer ID.
            get_hexagons: Accessor for array of H3 index strings.
            get_fill_color: Accessor for fill color [r, g, b, a].
            get_line_color: Accessor for stroke color [r, g, b, a].
            get_line_width: Accessor for line width.
            filled: Whether to fill clusters.
            stroked: Whether to stroke clusters.
            extruded: Whether to render as 3D.
            elevation_scale: Elevation multiplier.
            pickable: Whether layer responds to hover/click.
            opacity: Layer opacity.
            **kwargs: Additional H3ClusterLayer props.
        """
        layer_id = name or f"h3cluster-{len(self._deck_layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addH3ClusterLayer",
            id=layer_id,
            data=processed_data,
            getHexagons=get_hexagons,
            getFillColor=get_fill_color or [51, 136, 255, 128],
            getLineColor=get_line_color or [0, 0, 0, 255],
            getLineWidth=get_line_width,
            filled=filled,
            stroked=stroked,
            extruded=extruded,
            elevationScale=elevation_scale,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._deck_layers = {
            **self._deck_layers,
            layer_id: {"type": "H3ClusterLayer", "id": layer_id},
        }

    def add_s2_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_s2_token: Union[str, Callable] = "s2Token",
        get_fill_color: Union[List[int], str, Callable] = None,
        get_line_color: Union[List[int], str, Callable] = None,
        get_line_width: Union[float, str, Callable] = 1,
        get_elevation: Union[float, str, Callable] = 0,
        filled: bool = True,
        stroked: bool = True,
        extruded: bool = False,
        wireframe: bool = False,
        elevation_scale: float = 1,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add an S2 layer for S2 geometry cell visualization.

        Args:
            data: Array of data objects with S2 token.
            name: Layer ID.
            get_s2_token: Accessor for S2 token string.
            get_fill_color: Accessor for fill color [r, g, b, a].
            get_line_color: Accessor for stroke color [r, g, b, a].
            get_line_width: Accessor for line width.
            get_elevation: Accessor for 3D extrusion height.
            filled: Whether to fill cells.
            stroked: Whether to stroke cells.
            extruded: Whether to render as 3D.
            wireframe: Whether to render wireframe.
            elevation_scale: Elevation multiplier.
            pickable: Whether layer responds to hover/click.
            opacity: Layer opacity.
            **kwargs: Additional S2Layer props.
        """
        layer_id = name or f"s2-{len(self._deck_layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addS2Layer",
            id=layer_id,
            data=processed_data,
            getS2Token=get_s2_token,
            getFillColor=get_fill_color or [51, 136, 255, 128],
            getLineColor=get_line_color or [0, 0, 0, 255],
            getLineWidth=get_line_width,
            getElevation=get_elevation,
            filled=filled,
            stroked=stroked,
            extruded=extruded,
            wireframe=wireframe,
            elevationScale=elevation_scale,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._deck_layers = {
            **self._deck_layers,
            layer_id: {"type": "S2Layer", "id": layer_id},
        }

    def add_quadkey_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_quadkey: Union[str, Callable] = "quadkey",
        get_fill_color: Union[List[int], str, Callable] = None,
        get_line_color: Union[List[int], str, Callable] = None,
        get_line_width: Union[float, str, Callable] = 1,
        get_elevation: Union[float, str, Callable] = 0,
        filled: bool = True,
        stroked: bool = True,
        extruded: bool = False,
        wireframe: bool = False,
        elevation_scale: float = 1,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add a Quadkey layer for Bing Maps tile index visualization.

        Args:
            data: Array of data objects with quadkey.
            name: Layer ID.
            get_quadkey: Accessor for quadkey string.
            get_fill_color: Accessor for fill color [r, g, b, a].
            get_line_color: Accessor for stroke color [r, g, b, a].
            get_line_width: Accessor for line width.
            get_elevation: Accessor for 3D extrusion height.
            filled: Whether to fill cells.
            stroked: Whether to stroke cells.
            extruded: Whether to render as 3D.
            wireframe: Whether to render wireframe.
            elevation_scale: Elevation multiplier.
            pickable: Whether layer responds to hover/click.
            opacity: Layer opacity.
            **kwargs: Additional QuadkeyLayer props.
        """
        layer_id = name or f"quadkey-{len(self._deck_layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addQuadkeyLayer",
            id=layer_id,
            data=processed_data,
            getQuadkey=get_quadkey,
            getFillColor=get_fill_color or [51, 136, 255, 128],
            getLineColor=get_line_color or [0, 0, 0, 255],
            getLineWidth=get_line_width,
            getElevation=get_elevation,
            filled=filled,
            stroked=stroked,
            extruded=extruded,
            wireframe=wireframe,
            elevationScale=elevation_scale,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._deck_layers = {
            **self._deck_layers,
            layer_id: {"type": "QuadkeyLayer", "id": layer_id},
        }

    def add_geohash_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_geohash: Union[str, Callable] = "geohash",
        get_fill_color: Union[List[int], str, Callable] = None,
        get_line_color: Union[List[int], str, Callable] = None,
        get_line_width: Union[float, str, Callable] = 1,
        get_elevation: Union[float, str, Callable] = 0,
        filled: bool = True,
        stroked: bool = True,
        extruded: bool = False,
        wireframe: bool = False,
        elevation_scale: float = 1,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add a Geohash layer for geohash cell visualization.

        Args:
            data: Array of data objects with geohash.
            name: Layer ID.
            get_geohash: Accessor for geohash string.
            get_fill_color: Accessor for fill color [r, g, b, a].
            get_line_color: Accessor for stroke color [r, g, b, a].
            get_line_width: Accessor for line width.
            get_elevation: Accessor for 3D extrusion height.
            filled: Whether to fill cells.
            stroked: Whether to stroke cells.
            extruded: Whether to render as 3D.
            wireframe: Whether to render wireframe.
            elevation_scale: Elevation multiplier.
            pickable: Whether layer responds to hover/click.
            opacity: Layer opacity.
            **kwargs: Additional GeohashLayer props.
        """
        layer_id = name or f"geohash-{len(self._deck_layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addGeohashLayer",
            id=layer_id,
            data=processed_data,
            getGeohash=get_geohash,
            getFillColor=get_fill_color or [51, 136, 255, 128],
            getLineColor=get_line_color or [0, 0, 0, 255],
            getLineWidth=get_line_width,
            getElevation=get_elevation,
            filled=filled,
            stroked=stroked,
            extruded=extruded,
            wireframe=wireframe,
            elevationScale=elevation_scale,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._deck_layers = {
            **self._deck_layers,
            layer_id: {"type": "GeohashLayer", "id": layer_id},
        }

    def add_wms_layer(
        self,
        data: str,
        name: Optional[str] = None,
        service_type: str = "wms",
        layers: Optional[List[str]] = None,
        srs: Optional[str] = None,
        pickable: bool = False,
        visible: bool = True,
        opacity: float = 1.0,
        **kwargs,
    ) -> None:
        """Add a WMS layer for OGC Web Map Service visualization.

        Args:
            data: WMS base URL.
            name: Layer ID.
            service_type: Service type ('wms' or 'template').
            layers: WMS layer names to request.
            srs: Spatial reference system (e.g., 'EPSG:4326').
            pickable: Whether layer responds to hover/click.
            visible: Whether layer is visible.
            opacity: Layer opacity (0-1).
            **kwargs: Additional WMSLayer props.
        """
        layer_id = name or f"wms-{len(self._deck_layers)}"

        self.call_js_method(
            "addWMSLayer",
            id=layer_id,
            data=data,
            serviceType=service_type,
            layers=layers,
            srs=srs,
            pickable=pickable,
            visible=visible,
            opacity=opacity,
            **kwargs,
        )

        self._deck_layers = {
            **self._deck_layers,
            layer_id: {"type": "WMSLayer", "id": layer_id},
        }

    def add_simple_mesh_layer(
        self,
        data: Any,
        mesh: str,
        name: Optional[str] = None,
        texture: Optional[str] = None,
        get_position: Union[str, Callable] = "coordinates",
        get_color: Union[List[int], str, Callable] = None,
        get_orientation: Union[str, Callable] = None,
        get_scale: Union[str, Callable] = None,
        get_translation: Union[str, Callable] = None,
        size_scale: float = 1,
        wireframe: bool = False,
        pickable: bool = True,
        opacity: float = 1.0,
        **kwargs,
    ) -> None:
        """Add a simple mesh layer for 3D mesh visualization.

        Args:
            data: Array of data objects with position coordinates.
            mesh: URL to OBJ/glTF mesh file.
            name: Layer ID.
            texture: URL to texture image.
            get_position: Accessor for mesh position [lng, lat, z].
            get_color: Accessor for mesh color [r, g, b, a].
            get_orientation: Accessor for mesh orientation [pitch, yaw, roll].
            get_scale: Accessor for mesh scale [x, y, z].
            get_translation: Accessor for mesh translation [x, y, z].
            size_scale: Global size multiplier.
            wireframe: Whether to render as wireframe.
            pickable: Whether layer responds to hover/click.
            opacity: Layer opacity (0-1).
            **kwargs: Additional SimpleMeshLayer props.
        """
        layer_id = name or f"simplemesh-{len(self._deck_layers)}"
        processed_data = self._process_deck_data(data)

        layer_kwargs = {
            "id": layer_id,
            "data": processed_data,
            "mesh": mesh,
            "getPosition": get_position,
            "getColor": get_color or [255, 255, 255, 255],
            "sizeScale": size_scale,
            "wireframe": wireframe,
            "pickable": pickable,
            "opacity": opacity,
        }

        if texture:
            layer_kwargs["texture"] = texture
        if get_orientation:
            layer_kwargs["getOrientation"] = get_orientation
        if get_scale:
            layer_kwargs["getScale"] = get_scale
        if get_translation:
            layer_kwargs["getTranslation"] = get_translation

        layer_kwargs.update(kwargs)
        self.call_js_method("addSimpleMeshLayer", **layer_kwargs)

        self._deck_layers = {
            **self._deck_layers,
            layer_id: {"type": "SimpleMeshLayer", "id": layer_id},
        }

    def add_scenegraph_layer(
        self,
        data: Any,
        scenegraph: str,
        name: Optional[str] = None,
        get_position: Union[str, Callable] = "coordinates",
        get_color: Union[List[int], str, Callable] = None,
        get_orientation: Union[str, Callable] = None,
        get_scale: Union[str, Callable] = None,
        get_translation: Union[str, Callable] = None,
        size_scale: float = 1,
        size_min_pixels: float = 0,
        size_max_pixels: float = 10000,
        pickable: bool = True,
        opacity: float = 1.0,
        **kwargs,
    ) -> None:
        """Add a scenegraph layer for glTF model visualization.

        Args:
            data: Array of data objects with position coordinates.
            scenegraph: URL to glTF/GLB model file.
            name: Layer ID.
            get_position: Accessor for model position [lng, lat, z].
            get_color: Accessor for model tint color [r, g, b, a].
            get_orientation: Accessor for model orientation [pitch, yaw, roll].
            get_scale: Accessor for model scale [x, y, z].
            get_translation: Accessor for model translation [x, y, z].
            size_scale: Global size multiplier.
            size_min_pixels: Minimum model size in pixels.
            size_max_pixels: Maximum model size in pixels.
            pickable: Whether layer responds to hover/click.
            opacity: Layer opacity (0-1).
            **kwargs: Additional ScenegraphLayer props.
        """
        layer_id = name or f"scenegraph-{len(self._deck_layers)}"
        processed_data = self._process_deck_data(data)

        layer_kwargs = {
            "id": layer_id,
            "data": processed_data,
            "scenegraph": scenegraph,
            "getPosition": get_position,
            "getColor": get_color or [255, 255, 255, 255],
            "sizeScale": size_scale,
            "sizeMinPixels": size_min_pixels,
            "sizeMaxPixels": size_max_pixels,
            "pickable": pickable,
            "opacity": opacity,
        }

        if get_orientation:
            layer_kwargs["getOrientation"] = get_orientation
        if get_scale:
            layer_kwargs["getScale"] = get_scale
        if get_translation:
            layer_kwargs["getTranslation"] = get_translation

        layer_kwargs.update(kwargs)
        self.call_js_method("addScenegraphLayer", **layer_kwargs)

        self._deck_layers = {
            **self._deck_layers,
            layer_id: {"type": "ScenegraphLayer", "id": layer_id},
        }

    def remove_cog_layer(self, layer_id: str) -> None:
        """Remove a COG layer.

        Args:
            layer_id: Layer identifier to remove.
        """
        self.remove_deck_layer(layer_id)

    # -------------------------------------------------------------------------
    # DeckGL Layer Management
    # -------------------------------------------------------------------------

    def remove_deck_layer(self, layer_id: str) -> None:
        """Remove a deck.gl layer.

        Args:
            layer_id: Layer identifier to remove.
        """
        if layer_id in self._deck_layers:
            layers = dict(self._deck_layers)
            del layers[layer_id]
            self._deck_layers = layers
        self.call_js_method("removeDeckLayer", layer_id)

    def set_deck_layer_visibility(self, layer_id: str, visible: bool) -> None:
        """Set deck.gl layer visibility.

        Args:
            layer_id: Layer identifier.
            visible: Whether layer should be visible.
        """
        self.call_js_method("setDeckLayerVisibility", layer_id, visible)

    # -------------------------------------------------------------------------
    # Data Processing Helpers
    # -------------------------------------------------------------------------

    def _process_deck_data(self, data: Any) -> Any:
        """Process data for deck.gl layers.

        Handles GeoDataFrame, GeoJSON, and list of dicts.

        Args:
            data: Input data in various formats.

        Returns:
            Processed data suitable for deck.gl.
        """
        # Handle GeoDataFrame
        if hasattr(data, "__geo_interface__"):
            return json.loads(data.to_json())

        # Handle file path
        if isinstance(data, (str, Path)):
            path = Path(data)
            if path.exists() and path.suffix.lower() in [".geojson", ".json"]:
                with open(path) as f:
                    return json.load(f)
            # Could be URL, return as-is
            return str(data)

        # Handle dict (GeoJSON or config)
        if isinstance(data, dict):
            return data

        # Handle list of dicts
        if isinstance(data, list):
            return data

        return data

    # -------------------------------------------------------------------------
    # HTML Export
    # -------------------------------------------------------------------------

    def _generate_html_template(self) -> str:
        """Generate standalone HTML for the DeckGL map."""
        template_path = Path(__file__).parent / "templates" / "deckgl.html"

        if template_path.exists():
            template = template_path.read_text(encoding="utf-8")
        else:
            template = self._get_default_template()

        # Serialize state
        state = {
            "center": self.center,
            "zoom": self.zoom,
            "style": self.style,
            "bearing": self.bearing,
            "pitch": self.pitch,
            "width": self.width,
            "height": self.height,
            "layers": self._layers,
            "sources": self._sources,
            "controls": self._controls,
            "deckLayers": self._deck_layers,
            "js_calls": self._js_calls,
        }

        template = template.replace("{{state}}", json.dumps(state, indent=2))
        return template

__init__(self, center=(0.0, 0.0), zoom=2.0, width='100%', height='600px', style='https://demotiles.maplibre.org/style.json', bearing=0.0, pitch=0.0, max_pitch=85.0, controls=None, **kwargs) special

Initialize a DeckGL map.

Parameters:

Name Type Description Default
center Tuple[float, float]

Map center as (longitude, latitude).

(0.0, 0.0)
zoom float

Initial zoom level.

2.0
width str

Map width as CSS string.

'100%'
height str

Map height as CSS string.

'600px'
style Union[str, Dict]

MapLibre style URL or style object.

'https://demotiles.maplibre.org/style.json'
bearing float

Map bearing in degrees.

0.0
pitch float

Map pitch in degrees.

0.0
max_pitch float

Maximum pitch angle in degrees (default: 85).

85.0
controls Optional[Dict[str, Any]]

Dict of controls to add (e.g., {"navigation": True}).

None
**kwargs

Additional widget arguments.

{}
Source code in anymap_ts/deckgl.py
def __init__(
    self,
    center: Tuple[float, float] = (0.0, 0.0),
    zoom: float = 2.0,
    width: str = "100%",
    height: str = "600px",
    style: Union[str, Dict] = "https://demotiles.maplibre.org/style.json",
    bearing: float = 0.0,
    pitch: float = 0.0,
    max_pitch: float = 85.0,
    controls: Optional[Dict[str, Any]] = None,
    **kwargs,
):
    """Initialize a DeckGL map.

    Args:
        center: Map center as (longitude, latitude).
        zoom: Initial zoom level.
        width: Map width as CSS string.
        height: Map height as CSS string.
        style: MapLibre style URL or style object.
        bearing: Map bearing in degrees.
        pitch: Map pitch in degrees.
        max_pitch: Maximum pitch angle in degrees (default: 85).
        controls: Dict of controls to add (e.g., {"navigation": True}).
        **kwargs: Additional widget arguments.
    """
    super().__init__(
        center=center,
        zoom=zoom,
        width=width,
        height=height,
        style=style,
        bearing=bearing,
        pitch=pitch,
        max_pitch=max_pitch,
        controls=controls,
        **kwargs,
    )
    self._deck_layers = {}

add_arc_layer(self, data, name=None, get_source_position='source', get_target_position='target', get_source_color=None, get_target_color=None, get_width=1, pickable=True, opacity=0.8, **kwargs)

Add an arc layer for origin-destination visualization.

Parameters:

Name Type Description Default
data Any

Array of data objects with source/target coordinates.

required
name Optional[str]

Layer ID.

None
get_source_position Union[str, Callable]

Accessor for source position [lng, lat].

'source'
get_target_position Union[str, Callable]

Accessor for target position [lng, lat].

'target'
get_source_color Union[List[int], str, Callable]

Accessor for source color [r, g, b, a].

None
get_target_color Union[List[int], str, Callable]

Accessor for target color [r, g, b, a].

None
get_width Union[float, str, Callable]

Accessor for arc width.

1
pickable bool

Whether layer responds to hover/click.

True
opacity float

Layer opacity.

0.8
**kwargs

Additional layer props.

{}
Source code in anymap_ts/deckgl.py
def add_arc_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_source_position: Union[str, Callable] = "source",
    get_target_position: Union[str, Callable] = "target",
    get_source_color: Union[List[int], str, Callable] = None,
    get_target_color: Union[List[int], str, Callable] = None,
    get_width: Union[float, str, Callable] = 1,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add an arc layer for origin-destination visualization.

    Args:
        data: Array of data objects with source/target coordinates.
        name: Layer ID.
        get_source_position: Accessor for source position [lng, lat].
        get_target_position: Accessor for target position [lng, lat].
        get_source_color: Accessor for source color [r, g, b, a].
        get_target_color: Accessor for target color [r, g, b, a].
        get_width: Accessor for arc width.
        pickable: Whether layer responds to hover/click.
        opacity: Layer opacity.
        **kwargs: Additional layer props.
    """
    layer_id = name or f"arc-{len(self._deck_layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addArcLayer",
        id=layer_id,
        data=processed_data,
        getSourcePosition=get_source_position,
        getTargetPosition=get_target_position,
        getSourceColor=get_source_color or [51, 136, 255, 255],
        getTargetColor=get_target_color or [255, 136, 51, 255],
        getWidth=get_width,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._deck_layers = {
        **self._deck_layers,
        layer_id: {"type": "ArcLayer", "id": layer_id},
    }

add_bitmap_layer(self, image, bounds, name=None, opacity=1.0, visible=True, pickable=False, desaturate=0, transparent_color=None, tint_color=None, **kwargs)

Add a bitmap layer for raster image overlay.

Parameters:

Name Type Description Default
image str

URL or data URI of the image.

required
bounds List[float]

Bounding box [west, south, east, north].

required
name Optional[str]

Layer ID.

None
opacity float

Layer opacity (0-1).

1.0
visible bool

Whether layer is visible.

True
pickable bool

Whether layer responds to hover/click.

False
desaturate float

Desaturation amount (0-1).

0
transparent_color Optional[List[int]]

Color to make transparent [r, g, b, a].

None
tint_color Optional[List[int]]

Color to tint the image [r, g, b].

None
**kwargs

Additional BitmapLayer props.

{}
Source code in anymap_ts/deckgl.py
def add_bitmap_layer(
    self,
    image: str,
    bounds: List[float],
    name: Optional[str] = None,
    opacity: float = 1.0,
    visible: bool = True,
    pickable: bool = False,
    desaturate: float = 0,
    transparent_color: Optional[List[int]] = None,
    tint_color: Optional[List[int]] = None,
    **kwargs,
) -> None:
    """Add a bitmap layer for raster image overlay.

    Args:
        image: URL or data URI of the image.
        bounds: Bounding box [west, south, east, north].
        name: Layer ID.
        opacity: Layer opacity (0-1).
        visible: Whether layer is visible.
        pickable: Whether layer responds to hover/click.
        desaturate: Desaturation amount (0-1).
        transparent_color: Color to make transparent [r, g, b, a].
        tint_color: Color to tint the image [r, g, b].
        **kwargs: Additional BitmapLayer props.
    """
    layer_id = name or f"bitmap-{len(self._deck_layers)}"

    self.call_js_method(
        "addBitmapLayer",
        id=layer_id,
        image=image,
        bounds=bounds,
        opacity=opacity,
        visible=visible,
        pickable=pickable,
        desaturate=desaturate,
        transparentColor=transparent_color or [0, 0, 0, 0],
        tintColor=tint_color or [255, 255, 255],
        **kwargs,
    )

    self._deck_layers = {
        **self._deck_layers,
        layer_id: {"type": "BitmapLayer", "id": layer_id},
    }

add_cog_layer(self, url, name=None, opacity=1.0, visible=True, debug=False, debug_opacity=0.25, max_error=0.125, fit_bounds=True, before_id=None, **kwargs)

Add a Cloud Optimized GeoTIFF (COG) layer using @developmentseed/deck.gl-geotiff.

This method renders COG files directly in the browser using GPU-accelerated deck.gl rendering with automatic reprojection support.

Parameters:

Name Type Description Default
url str

URL to the Cloud Optimized GeoTIFF file.

required
name Optional[str]

Layer ID. If None, auto-generated.

None
opacity float

Layer opacity (0-1).

1.0
visible bool

Whether layer is visible.

True
debug bool

Show reprojection mesh for debugging.

False
debug_opacity float

Opacity of debug mesh (0-1).

0.25
max_error float

Maximum reprojection error in pixels. Lower values create denser mesh for better accuracy.

0.125
fit_bounds bool

Whether to fit map to COG bounds after loading.

True
before_id Optional[str]

ID of layer to insert before.

None
**kwargs

Additional COGLayer props.

{}

Examples:

>>> m = DeckGLMap()
>>> m.add_cog_layer(
...     "https://example.com/landcover.tif",
...     name="landcover",
...     opacity=0.8
... )
Source code in anymap_ts/deckgl.py
def add_cog_layer(
    self,
    url: str,
    name: Optional[str] = None,
    opacity: float = 1.0,
    visible: bool = True,
    debug: bool = False,
    debug_opacity: float = 0.25,
    max_error: float = 0.125,
    fit_bounds: bool = True,
    before_id: Optional[str] = None,
    **kwargs,
) -> None:
    """Add a Cloud Optimized GeoTIFF (COG) layer using @developmentseed/deck.gl-geotiff.

    This method renders COG files directly in the browser using GPU-accelerated
    deck.gl rendering with automatic reprojection support.

    Args:
        url: URL to the Cloud Optimized GeoTIFF file.
        name: Layer ID. If None, auto-generated.
        opacity: Layer opacity (0-1).
        visible: Whether layer is visible.
        debug: Show reprojection mesh for debugging.
        debug_opacity: Opacity of debug mesh (0-1).
        max_error: Maximum reprojection error in pixels. Lower values
            create denser mesh for better accuracy.
        fit_bounds: Whether to fit map to COG bounds after loading.
        before_id: ID of layer to insert before.
        **kwargs: Additional COGLayer props.

    Example:
        >>> m = DeckGLMap()
        >>> m.add_cog_layer(
        ...     "https://example.com/landcover.tif",
        ...     name="landcover",
        ...     opacity=0.8
        ... )
    """
    # Use a monotonically increasing counter to avoid ID collisions when layers are removed.
    counter = getattr(self, "_cog_layer_counter", 0)
    layer_id = name or f"cog-{counter}"
    self._cog_layer_counter = counter + 1

    self.call_js_method(
        "addCOGLayer",
        id=layer_id,
        geotiff=url,
        opacity=opacity,
        visible=visible,
        debug=debug,
        debugOpacity=debug_opacity,
        maxError=max_error,
        fitBounds=fit_bounds,
        beforeId=before_id,
        **kwargs,
    )

    self._deck_layers = {
        **self._deck_layers,
        layer_id: {"type": "COGLayer", "id": layer_id, "url": url},
    }

add_column_layer(self, data, name=None, get_position='coordinates', get_fill_color=None, get_line_color=None, get_elevation=1000, radius=1000, disk_resolution=20, elevation_scale=1, coverage=1, extruded=True, filled=True, stroked=False, wireframe=False, pickable=True, opacity=0.8, **kwargs)

Add a column layer for 3D column/bar visualization.

Parameters:

Name Type Description Default
data Any

Array of data objects with position coordinates.

required
name Optional[str]

Layer ID.

None
get_position Union[str, Callable]

Accessor for column position [lng, lat].

'coordinates'
get_fill_color Union[List[int], str, Callable]

Accessor for fill color [r, g, b, a].

None
get_line_color Union[List[int], str, Callable]

Accessor for stroke color [r, g, b, a].

None
get_elevation Union[float, str, Callable]

Accessor for column height.

1000
radius float

Column radius in meters.

1000
disk_resolution int

Number of sides for column polygon.

20
elevation_scale float

Elevation multiplier.

1
coverage float

Column coverage (0-1).

1
extruded bool

Whether to extrude columns.

True
filled bool

Whether to fill columns.

True
stroked bool

Whether to stroke columns.

False
wireframe bool

Whether to render as wireframe.

False
pickable bool

Whether layer responds to hover/click.

True
opacity float

Layer opacity.

0.8
**kwargs

Additional ColumnLayer props.

{}
Source code in anymap_ts/deckgl.py
def add_column_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_position: Union[str, Callable] = "coordinates",
    get_fill_color: Union[List[int], str, Callable] = None,
    get_line_color: Union[List[int], str, Callable] = None,
    get_elevation: Union[float, str, Callable] = 1000,
    radius: float = 1000,
    disk_resolution: int = 20,
    elevation_scale: float = 1,
    coverage: float = 1,
    extruded: bool = True,
    filled: bool = True,
    stroked: bool = False,
    wireframe: bool = False,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add a column layer for 3D column/bar visualization.

    Args:
        data: Array of data objects with position coordinates.
        name: Layer ID.
        get_position: Accessor for column position [lng, lat].
        get_fill_color: Accessor for fill color [r, g, b, a].
        get_line_color: Accessor for stroke color [r, g, b, a].
        get_elevation: Accessor for column height.
        radius: Column radius in meters.
        disk_resolution: Number of sides for column polygon.
        elevation_scale: Elevation multiplier.
        coverage: Column coverage (0-1).
        extruded: Whether to extrude columns.
        filled: Whether to fill columns.
        stroked: Whether to stroke columns.
        wireframe: Whether to render as wireframe.
        pickable: Whether layer responds to hover/click.
        opacity: Layer opacity.
        **kwargs: Additional ColumnLayer props.
    """
    layer_id = name or f"column-{len(self._deck_layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addColumnLayer",
        id=layer_id,
        data=processed_data,
        getPosition=get_position,
        getFillColor=get_fill_color or [255, 140, 0, 200],
        getLineColor=get_line_color or [0, 0, 0, 255],
        getElevation=get_elevation,
        radius=radius,
        diskResolution=disk_resolution,
        elevationScale=elevation_scale,
        coverage=coverage,
        extruded=extruded,
        filled=filled,
        stroked=stroked,
        wireframe=wireframe,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._deck_layers = {
        **self._deck_layers,
        layer_id: {"type": "ColumnLayer", "id": layer_id},
    }

add_contour_layer(self, data, name=None, get_position='coordinates', get_weight=1, cell_size=200, contours=None, pickable=True, opacity=1, **kwargs)

Add a contour layer for isoline visualization.

Parameters:

Name Type Description Default
data Any

Array of data objects with position coordinates.

required
name Optional[str]

Layer ID.

None
get_position Union[str, Callable]

Accessor for point position [lng, lat].

'coordinates'
get_weight Union[float, str, Callable]

Accessor for point weight.

1
cell_size float

Grid cell size for aggregation.

200
contours Optional[List[Dict]]

Contour definitions [{threshold, color, strokeWidth}, ...].

None
pickable bool

Whether layer responds to hover/click.

True
opacity float

Layer opacity.

1
**kwargs

Additional layer props.

{}
Source code in anymap_ts/deckgl.py
def add_contour_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_position: Union[str, Callable] = "coordinates",
    get_weight: Union[float, str, Callable] = 1,
    cell_size: float = 200,
    contours: Optional[List[Dict]] = None,
    pickable: bool = True,
    opacity: float = 1,
    **kwargs,
) -> None:
    """Add a contour layer for isoline visualization.

    Args:
        data: Array of data objects with position coordinates.
        name: Layer ID.
        get_position: Accessor for point position [lng, lat].
        get_weight: Accessor for point weight.
        cell_size: Grid cell size for aggregation.
        contours: Contour definitions [{threshold, color, strokeWidth}, ...].
        pickable: Whether layer responds to hover/click.
        opacity: Layer opacity.
        **kwargs: Additional layer props.
    """
    layer_id = name or f"contour-{len(self._deck_layers)}"
    processed_data = self._process_deck_data(data)

    default_contours = [
        {"threshold": 1, "color": [255, 255, 255], "strokeWidth": 1},
        {"threshold": 5, "color": [51, 136, 255], "strokeWidth": 2},
        {"threshold": 10, "color": [0, 0, 255], "strokeWidth": 3},
    ]

    self.call_js_method(
        "addContourLayer",
        id=layer_id,
        data=processed_data,
        getPosition=get_position,
        getWeight=get_weight,
        cellSize=cell_size,
        contours=contours or default_contours,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._deck_layers = {
        **self._deck_layers,
        layer_id: {"type": "ContourLayer", "id": layer_id},
    }

add_deckgl_layer(self, layer_type, data, name=None, **kwargs)

Add a generic deck.gl layer to the map.

This method provides a flexible way to add any supported deck.gl layer type using a single interface. For commonly used layers, prefer the specific methods (e.g., add_scatterplot_layer) for better IDE support.

Parameters:

Name Type Description Default
layer_type str

The deck.gl layer type. Supported types include: 'ScatterplotLayer', 'ArcLayer', 'PathLayer', 'PolygonLayer', 'HexagonLayer', 'HeatmapLayer', 'GridLayer', 'IconLayer', 'TextLayer', 'GeoJsonLayer', 'ContourLayer', 'ScreenGridLayer', 'PointCloudLayer', 'TripsLayer', 'LineLayer'.

required
data Any

Array of data objects or GeoJSON.

required
name Optional[str]

Layer ID. If None, auto-generated from layer_type.

None
**kwargs

Layer-specific properties passed directly to deck.gl. Common properties include: - opacity: Layer opacity (0-1) - pickable: Whether layer responds to hover/click - getPosition: Accessor for position coordinates - getColor/getFillColor/getLineColor: Color accessors

{}

Examples:

>>> m = DeckGLMap()
>>> # Add a TripsLayer with animation
>>> m.add_deckgl_layer(
...     'TripsLayer',
...     data=trips_data,
...     getPath='waypoints',
...     getTimestamps='timestamps',
...     getColor=[253, 128, 93],
...     trailLength=180,
... )
>>> # Add a LineLayer
>>> m.add_deckgl_layer(
...     'LineLayer',
...     data=lines_data,
...     getSourcePosition='source',
...     getTargetPosition='target',
...     getColor=[0, 128, 255],
... )
Source code in anymap_ts/deckgl.py
def add_deckgl_layer(
    self,
    layer_type: str,
    data: Any,
    name: Optional[str] = None,
    **kwargs,
) -> None:
    """Add a generic deck.gl layer to the map.

    This method provides a flexible way to add any supported deck.gl layer
    type using a single interface. For commonly used layers, prefer the
    specific methods (e.g., add_scatterplot_layer) for better IDE support.

    Args:
        layer_type: The deck.gl layer type. Supported types include:
            'ScatterplotLayer', 'ArcLayer', 'PathLayer', 'PolygonLayer',
            'HexagonLayer', 'HeatmapLayer', 'GridLayer', 'IconLayer',
            'TextLayer', 'GeoJsonLayer', 'ContourLayer', 'ScreenGridLayer',
            'PointCloudLayer', 'TripsLayer', 'LineLayer'.
        data: Array of data objects or GeoJSON.
        name: Layer ID. If None, auto-generated from layer_type.
        **kwargs: Layer-specific properties passed directly to deck.gl.
            Common properties include:
            - opacity: Layer opacity (0-1)
            - pickable: Whether layer responds to hover/click
            - getPosition: Accessor for position coordinates
            - getColor/getFillColor/getLineColor: Color accessors

    Example:
        >>> m = DeckGLMap()
        >>> # Add a TripsLayer with animation
        >>> m.add_deckgl_layer(
        ...     'TripsLayer',
        ...     data=trips_data,
        ...     getPath='waypoints',
        ...     getTimestamps='timestamps',
        ...     getColor=[253, 128, 93],
        ...     trailLength=180,
        ... )
        >>> # Add a LineLayer
        >>> m.add_deckgl_layer(
        ...     'LineLayer',
        ...     data=lines_data,
        ...     getSourcePosition='source',
        ...     getTargetPosition='target',
        ...     getColor=[0, 128, 255],
        ... )
    """
    # Normalize layer type and create prefix
    layer_type_clean = layer_type.replace("Layer", "")
    prefix = layer_type_clean.lower()
    layer_id = name or f"{prefix}-{len(self._deck_layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addDeckGLLayer",
        layerType=layer_type,
        id=layer_id,
        data=processed_data,
        **kwargs,
    )

    self._deck_layers = {
        **self._deck_layers,
        layer_id: {"type": layer_type, "id": layer_id},
    }

add_geohash_layer(self, data, name=None, get_geohash='geohash', get_fill_color=None, get_line_color=None, get_line_width=1, get_elevation=0, filled=True, stroked=True, extruded=False, wireframe=False, elevation_scale=1, pickable=True, opacity=0.8, **kwargs)

Add a Geohash layer for geohash cell visualization.

Parameters:

Name Type Description Default
data Any

Array of data objects with geohash.

required
name Optional[str]

Layer ID.

None
get_geohash Union[str, Callable]

Accessor for geohash string.

'geohash'
get_fill_color Union[List[int], str, Callable]

Accessor for fill color [r, g, b, a].

None
get_line_color Union[List[int], str, Callable]

Accessor for stroke color [r, g, b, a].

None
get_line_width Union[float, str, Callable]

Accessor for line width.

1
get_elevation Union[float, str, Callable]

Accessor for 3D extrusion height.

0
filled bool

Whether to fill cells.

True
stroked bool

Whether to stroke cells.

True
extruded bool

Whether to render as 3D.

False
wireframe bool

Whether to render wireframe.

False
elevation_scale float

Elevation multiplier.

1
pickable bool

Whether layer responds to hover/click.

True
opacity float

Layer opacity.

0.8
**kwargs

Additional GeohashLayer props.

{}
Source code in anymap_ts/deckgl.py
def add_geohash_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_geohash: Union[str, Callable] = "geohash",
    get_fill_color: Union[List[int], str, Callable] = None,
    get_line_color: Union[List[int], str, Callable] = None,
    get_line_width: Union[float, str, Callable] = 1,
    get_elevation: Union[float, str, Callable] = 0,
    filled: bool = True,
    stroked: bool = True,
    extruded: bool = False,
    wireframe: bool = False,
    elevation_scale: float = 1,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add a Geohash layer for geohash cell visualization.

    Args:
        data: Array of data objects with geohash.
        name: Layer ID.
        get_geohash: Accessor for geohash string.
        get_fill_color: Accessor for fill color [r, g, b, a].
        get_line_color: Accessor for stroke color [r, g, b, a].
        get_line_width: Accessor for line width.
        get_elevation: Accessor for 3D extrusion height.
        filled: Whether to fill cells.
        stroked: Whether to stroke cells.
        extruded: Whether to render as 3D.
        wireframe: Whether to render wireframe.
        elevation_scale: Elevation multiplier.
        pickable: Whether layer responds to hover/click.
        opacity: Layer opacity.
        **kwargs: Additional GeohashLayer props.
    """
    layer_id = name or f"geohash-{len(self._deck_layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addGeohashLayer",
        id=layer_id,
        data=processed_data,
        getGeohash=get_geohash,
        getFillColor=get_fill_color or [51, 136, 255, 128],
        getLineColor=get_line_color or [0, 0, 0, 255],
        getLineWidth=get_line_width,
        getElevation=get_elevation,
        filled=filled,
        stroked=stroked,
        extruded=extruded,
        wireframe=wireframe,
        elevationScale=elevation_scale,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._deck_layers = {
        **self._deck_layers,
        layer_id: {"type": "GeohashLayer", "id": layer_id},
    }

add_geojson_layer(self, data, name=None, get_fill_color=None, get_line_color=None, get_line_width=1, get_point_radius=5, get_elevation=0, extruded=False, wireframe=False, filled=True, stroked=True, line_width_min_pixels=1, point_radius_min_pixels=2, pickable=True, opacity=0.8, **kwargs)

Add a GeoJSON layer for rendering GeoJSON features.

Parameters:

Name Type Description Default
data Any

GeoJSON object or URL.

required
name Optional[str]

Layer ID.

None
get_fill_color Union[List[int], str, Callable]

Accessor for fill color [r, g, b, a].

None
get_line_color Union[List[int], str, Callable]

Accessor for stroke color [r, g, b, a].

None
get_line_width Union[float, str, Callable]

Accessor for stroke width.

1
get_point_radius Union[float, str, Callable]

Accessor for point radius.

5
get_elevation Union[float, str, Callable]

Accessor for 3D extrusion height.

0
extruded bool

Whether to render as 3D features.

False
wireframe bool

Whether to render wireframe (extruded only).

False
filled bool

Whether to fill features.

True
stroked bool

Whether to draw stroke.

True
line_width_min_pixels float

Minimum stroke width.

1
point_radius_min_pixels float

Minimum point radius.

2
pickable bool

Whether layer responds to hover/click.

True
opacity float

Layer opacity.

0.8
**kwargs

Additional layer props.

{}
Source code in anymap_ts/deckgl.py
def add_geojson_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_fill_color: Union[List[int], str, Callable] = None,
    get_line_color: Union[List[int], str, Callable] = None,
    get_line_width: Union[float, str, Callable] = 1,
    get_point_radius: Union[float, str, Callable] = 5,
    get_elevation: Union[float, str, Callable] = 0,
    extruded: bool = False,
    wireframe: bool = False,
    filled: bool = True,
    stroked: bool = True,
    line_width_min_pixels: float = 1,
    point_radius_min_pixels: float = 2,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add a GeoJSON layer for rendering GeoJSON features.

    Args:
        data: GeoJSON object or URL.
        name: Layer ID.
        get_fill_color: Accessor for fill color [r, g, b, a].
        get_line_color: Accessor for stroke color [r, g, b, a].
        get_line_width: Accessor for stroke width.
        get_point_radius: Accessor for point radius.
        get_elevation: Accessor for 3D extrusion height.
        extruded: Whether to render as 3D features.
        wireframe: Whether to render wireframe (extruded only).
        filled: Whether to fill features.
        stroked: Whether to draw stroke.
        line_width_min_pixels: Minimum stroke width.
        point_radius_min_pixels: Minimum point radius.
        pickable: Whether layer responds to hover/click.
        opacity: Layer opacity.
        **kwargs: Additional layer props.
    """
    layer_id = name or f"geojson-{len(self._deck_layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addGeoJsonLayer",
        id=layer_id,
        data=processed_data,
        getFillColor=get_fill_color or [51, 136, 255, 128],
        getLineColor=get_line_color or [0, 0, 0, 255],
        getLineWidth=get_line_width,
        getPointRadius=get_point_radius,
        getElevation=get_elevation,
        extruded=extruded,
        wireframe=wireframe,
        filled=filled,
        stroked=stroked,
        lineWidthMinPixels=line_width_min_pixels,
        pointRadiusMinPixels=point_radius_min_pixels,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._deck_layers = {
        **self._deck_layers,
        layer_id: {"type": "GeoJsonLayer", "id": layer_id},
    }

add_great_circle_layer(self, data, name=None, get_source_position='source', get_target_position='target', get_source_color=None, get_target_color=None, get_width=1, width_min_pixels=1, width_max_pixels=100, pickable=True, opacity=0.8, **kwargs)

Add a great circle layer for geodesic arc visualization.

Parameters:

Name Type Description Default
data Any

Array of data objects with source/target coordinates.

required
name Optional[str]

Layer ID.

None
get_source_position Union[str, Callable]

Accessor for source position [lng, lat].

'source'
get_target_position Union[str, Callable]

Accessor for target position [lng, lat].

'target'
get_source_color Union[List[int], str, Callable]

Accessor for source color [r, g, b, a].

None
get_target_color Union[List[int], str, Callable]

Accessor for target color [r, g, b, a].

None
get_width Union[float, str, Callable]

Accessor for line width.

1
width_min_pixels float

Minimum line width in pixels.

1
width_max_pixels float

Maximum line width in pixels.

100
pickable bool

Whether layer responds to hover/click.

True
opacity float

Layer opacity.

0.8
**kwargs

Additional GreatCircleLayer props.

{}
Source code in anymap_ts/deckgl.py
def add_great_circle_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_source_position: Union[str, Callable] = "source",
    get_target_position: Union[str, Callable] = "target",
    get_source_color: Union[List[int], str, Callable] = None,
    get_target_color: Union[List[int], str, Callable] = None,
    get_width: Union[float, str, Callable] = 1,
    width_min_pixels: float = 1,
    width_max_pixels: float = 100,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add a great circle layer for geodesic arc visualization.

    Args:
        data: Array of data objects with source/target coordinates.
        name: Layer ID.
        get_source_position: Accessor for source position [lng, lat].
        get_target_position: Accessor for target position [lng, lat].
        get_source_color: Accessor for source color [r, g, b, a].
        get_target_color: Accessor for target color [r, g, b, a].
        get_width: Accessor for line width.
        width_min_pixels: Minimum line width in pixels.
        width_max_pixels: Maximum line width in pixels.
        pickable: Whether layer responds to hover/click.
        opacity: Layer opacity.
        **kwargs: Additional GreatCircleLayer props.
    """
    layer_id = name or f"greatcircle-{len(self._deck_layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addGreatCircleLayer",
        id=layer_id,
        data=processed_data,
        getSourcePosition=get_source_position,
        getTargetPosition=get_target_position,
        getSourceColor=get_source_color or [51, 136, 255, 255],
        getTargetColor=get_target_color or [255, 136, 51, 255],
        getWidth=get_width,
        widthMinPixels=width_min_pixels,
        widthMaxPixels=width_max_pixels,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._deck_layers = {
        **self._deck_layers,
        layer_id: {"type": "GreatCircleLayer", "id": layer_id},
    }

add_grid_cell_layer(self, data, name=None, get_position='coordinates', get_color=None, get_elevation=1000, cell_size=200, coverage=1, elevation_scale=1, extruded=True, pickable=True, opacity=0.8, **kwargs)

Add a grid cell layer for pre-aggregated grid visualization.

Parameters:

Name Type Description Default
data Any

Array of data objects with position coordinates.

required
name Optional[str]

Layer ID.

None
get_position Union[str, Callable]

Accessor for cell position [lng, lat].

'coordinates'
get_color Union[List[int], str, Callable]

Accessor for cell color [r, g, b, a].

None
get_elevation Union[float, str, Callable]

Accessor for cell height.

1000
cell_size float

Cell size in meters.

200
coverage float

Cell coverage (0-1).

1
elevation_scale float

Elevation multiplier.

1
extruded bool

Whether to extrude cells.

True
pickable bool

Whether layer responds to hover/click.

True
opacity float

Layer opacity.

0.8
**kwargs

Additional GridCellLayer props.

{}
Source code in anymap_ts/deckgl.py
def add_grid_cell_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_position: Union[str, Callable] = "coordinates",
    get_color: Union[List[int], str, Callable] = None,
    get_elevation: Union[float, str, Callable] = 1000,
    cell_size: float = 200,
    coverage: float = 1,
    elevation_scale: float = 1,
    extruded: bool = True,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add a grid cell layer for pre-aggregated grid visualization.

    Args:
        data: Array of data objects with position coordinates.
        name: Layer ID.
        get_position: Accessor for cell position [lng, lat].
        get_color: Accessor for cell color [r, g, b, a].
        get_elevation: Accessor for cell height.
        cell_size: Cell size in meters.
        coverage: Cell coverage (0-1).
        elevation_scale: Elevation multiplier.
        extruded: Whether to extrude cells.
        pickable: Whether layer responds to hover/click.
        opacity: Layer opacity.
        **kwargs: Additional GridCellLayer props.
    """
    layer_id = name or f"gridcell-{len(self._deck_layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addGridCellLayer",
        id=layer_id,
        data=processed_data,
        getPosition=get_position,
        getColor=get_color or [255, 140, 0, 200],
        getElevation=get_elevation,
        cellSize=cell_size,
        coverage=coverage,
        elevationScale=elevation_scale,
        extruded=extruded,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._deck_layers = {
        **self._deck_layers,
        layer_id: {"type": "GridCellLayer", "id": layer_id},
    }

add_grid_layer(self, data, name=None, get_position='coordinates', cell_size=200, elevation_scale=4, extruded=True, color_range=None, pickable=True, opacity=0.8, **kwargs)

Add a grid layer for square grid aggregation visualization.

Parameters:

Name Type Description Default
data Any

Array of data objects with position coordinates.

required
name Optional[str]

Layer ID.

None
get_position Union[str, Callable]

Accessor for point position [lng, lat].

'coordinates'
cell_size float

Grid cell size in meters.

200
elevation_scale float

Elevation multiplier for 3D.

4
extruded bool

Whether to render as 3D cells.

True
color_range Optional[List[List[int]]]

Color gradient [[r, g, b], ...].

None
pickable bool

Whether layer responds to hover/click.

True
opacity float

Layer opacity.

0.8
**kwargs

Additional layer props.

{}
Source code in anymap_ts/deckgl.py
def add_grid_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_position: Union[str, Callable] = "coordinates",
    cell_size: float = 200,
    elevation_scale: float = 4,
    extruded: bool = True,
    color_range: Optional[List[List[int]]] = None,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add a grid layer for square grid aggregation visualization.

    Args:
        data: Array of data objects with position coordinates.
        name: Layer ID.
        get_position: Accessor for point position [lng, lat].
        cell_size: Grid cell size in meters.
        elevation_scale: Elevation multiplier for 3D.
        extruded: Whether to render as 3D cells.
        color_range: Color gradient [[r, g, b], ...].
        pickable: Whether layer responds to hover/click.
        opacity: Layer opacity.
        **kwargs: Additional layer props.
    """
    layer_id = name or f"grid-{len(self._deck_layers)}"
    processed_data = self._process_deck_data(data)

    default_color_range = [
        [1, 152, 189],
        [73, 227, 206],
        [216, 254, 181],
        [254, 237, 177],
        [254, 173, 84],
        [209, 55, 78],
    ]

    self.call_js_method(
        "addGridLayer",
        id=layer_id,
        data=processed_data,
        getPosition=get_position,
        cellSize=cell_size,
        elevationScale=elevation_scale,
        extruded=extruded,
        colorRange=color_range or default_color_range,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._deck_layers = {
        **self._deck_layers,
        layer_id: {"type": "GridLayer", "id": layer_id},
    }

add_h3_cluster_layer(self, data, name=None, get_hexagons='hexagons', get_fill_color=None, get_line_color=None, get_line_width=1, filled=True, stroked=True, extruded=False, elevation_scale=1, pickable=True, opacity=0.8, **kwargs)

Add an H3 cluster layer for grouped H3 cell visualization.

Parameters:

Name Type Description Default
data Any

Array of data objects with H3 index arrays.

required
name Optional[str]

Layer ID.

None
get_hexagons Union[str, Callable]

Accessor for array of H3 index strings.

'hexagons'
get_fill_color Union[List[int], str, Callable]

Accessor for fill color [r, g, b, a].

None
get_line_color Union[List[int], str, Callable]

Accessor for stroke color [r, g, b, a].

None
get_line_width Union[float, str, Callable]

Accessor for line width.

1
filled bool

Whether to fill clusters.

True
stroked bool

Whether to stroke clusters.

True
extruded bool

Whether to render as 3D.

False
elevation_scale float

Elevation multiplier.

1
pickable bool

Whether layer responds to hover/click.

True
opacity float

Layer opacity.

0.8
**kwargs

Additional H3ClusterLayer props.

{}
Source code in anymap_ts/deckgl.py
def add_h3_cluster_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_hexagons: Union[str, Callable] = "hexagons",
    get_fill_color: Union[List[int], str, Callable] = None,
    get_line_color: Union[List[int], str, Callable] = None,
    get_line_width: Union[float, str, Callable] = 1,
    filled: bool = True,
    stroked: bool = True,
    extruded: bool = False,
    elevation_scale: float = 1,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add an H3 cluster layer for grouped H3 cell visualization.

    Args:
        data: Array of data objects with H3 index arrays.
        name: Layer ID.
        get_hexagons: Accessor for array of H3 index strings.
        get_fill_color: Accessor for fill color [r, g, b, a].
        get_line_color: Accessor for stroke color [r, g, b, a].
        get_line_width: Accessor for line width.
        filled: Whether to fill clusters.
        stroked: Whether to stroke clusters.
        extruded: Whether to render as 3D.
        elevation_scale: Elevation multiplier.
        pickable: Whether layer responds to hover/click.
        opacity: Layer opacity.
        **kwargs: Additional H3ClusterLayer props.
    """
    layer_id = name or f"h3cluster-{len(self._deck_layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addH3ClusterLayer",
        id=layer_id,
        data=processed_data,
        getHexagons=get_hexagons,
        getFillColor=get_fill_color or [51, 136, 255, 128],
        getLineColor=get_line_color or [0, 0, 0, 255],
        getLineWidth=get_line_width,
        filled=filled,
        stroked=stroked,
        extruded=extruded,
        elevationScale=elevation_scale,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._deck_layers = {
        **self._deck_layers,
        layer_id: {"type": "H3ClusterLayer", "id": layer_id},
    }

add_h3_hexagon_layer(self, data, name=None, get_hexagon='hexagon', get_fill_color=None, get_line_color=None, get_elevation=0, filled=True, stroked=True, extruded=False, wireframe=False, elevation_scale=1, coverage=1, high_precision=False, pickable=True, opacity=0.8, **kwargs)

Add an H3 hexagon layer for H3 spatial index visualization.

Parameters:

Name Type Description Default
data Any

Array of data objects with H3 index.

required
name Optional[str]

Layer ID.

None
get_hexagon Union[str, Callable]

Accessor for H3 index string.

'hexagon'
get_fill_color Union[List[int], str, Callable]

Accessor for fill color [r, g, b, a].

None
get_line_color Union[List[int], str, Callable]

Accessor for stroke color [r, g, b, a].

None
get_elevation Union[float, str, Callable]

Accessor for 3D extrusion height.

0
filled bool

Whether to fill hexagons.

True
stroked bool

Whether to stroke hexagons.

True
extruded bool

Whether to render as 3D hexagons.

False
wireframe bool

Whether to render wireframe.

False
elevation_scale float

Elevation multiplier.

1
coverage float

Hexagon coverage (0-1).

1
high_precision bool

Use high precision rendering.

False
pickable bool

Whether layer responds to hover/click.

True
opacity float

Layer opacity.

0.8
**kwargs

Additional H3HexagonLayer props.

{}
Source code in anymap_ts/deckgl.py
def add_h3_hexagon_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_hexagon: Union[str, Callable] = "hexagon",
    get_fill_color: Union[List[int], str, Callable] = None,
    get_line_color: Union[List[int], str, Callable] = None,
    get_elevation: Union[float, str, Callable] = 0,
    filled: bool = True,
    stroked: bool = True,
    extruded: bool = False,
    wireframe: bool = False,
    elevation_scale: float = 1,
    coverage: float = 1,
    high_precision: bool = False,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add an H3 hexagon layer for H3 spatial index visualization.

    Args:
        data: Array of data objects with H3 index.
        name: Layer ID.
        get_hexagon: Accessor for H3 index string.
        get_fill_color: Accessor for fill color [r, g, b, a].
        get_line_color: Accessor for stroke color [r, g, b, a].
        get_elevation: Accessor for 3D extrusion height.
        filled: Whether to fill hexagons.
        stroked: Whether to stroke hexagons.
        extruded: Whether to render as 3D hexagons.
        wireframe: Whether to render wireframe.
        elevation_scale: Elevation multiplier.
        coverage: Hexagon coverage (0-1).
        high_precision: Use high precision rendering.
        pickable: Whether layer responds to hover/click.
        opacity: Layer opacity.
        **kwargs: Additional H3HexagonLayer props.
    """
    layer_id = name or f"h3hexagon-{len(self._deck_layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addH3HexagonLayer",
        id=layer_id,
        data=processed_data,
        getHexagon=get_hexagon,
        getFillColor=get_fill_color or [51, 136, 255, 128],
        getLineColor=get_line_color or [0, 0, 0, 255],
        getElevation=get_elevation,
        filled=filled,
        stroked=stroked,
        extruded=extruded,
        wireframe=wireframe,
        elevationScale=elevation_scale,
        coverage=coverage,
        highPrecision=high_precision,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._deck_layers = {
        **self._deck_layers,
        layer_id: {"type": "H3HexagonLayer", "id": layer_id},
    }

add_heatmap_layer(self, data, name=None, get_position='coordinates', get_weight=1, radius_pixels=30, intensity=1, threshold=0.05, color_range=None, opacity=1, **kwargs)

Add a heatmap layer for density visualization.

Parameters:

Name Type Description Default
data Any

Array of data objects with position coordinates.

required
name Optional[str]

Layer ID.

None
get_position Union[str, Callable]

Accessor for point position [lng, lat].

'coordinates'
get_weight Union[float, str, Callable]

Accessor for point weight.

1
radius_pixels float

Influence radius in pixels.

30
intensity float

Intensity multiplier.

1
threshold float

Minimum density threshold.

0.05
color_range Optional[List[List[int]]]

Color gradient [[r, g, b, a], ...].

None
opacity float

Layer opacity.

1
**kwargs

Additional layer props.

{}
Source code in anymap_ts/deckgl.py
def add_heatmap_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_position: Union[str, Callable] = "coordinates",
    get_weight: Union[float, str, Callable] = 1,
    radius_pixels: float = 30,
    intensity: float = 1,
    threshold: float = 0.05,
    color_range: Optional[List[List[int]]] = None,
    opacity: float = 1,
    **kwargs,
) -> None:
    """Add a heatmap layer for density visualization.

    Args:
        data: Array of data objects with position coordinates.
        name: Layer ID.
        get_position: Accessor for point position [lng, lat].
        get_weight: Accessor for point weight.
        radius_pixels: Influence radius in pixels.
        intensity: Intensity multiplier.
        threshold: Minimum density threshold.
        color_range: Color gradient [[r, g, b, a], ...].
        opacity: Layer opacity.
        **kwargs: Additional layer props.
    """
    layer_id = name or f"heatmap-{len(self._deck_layers)}"
    processed_data = self._process_deck_data(data)

    default_color_range = [
        [255, 255, 178, 25],
        [254, 217, 118, 85],
        [254, 178, 76, 127],
        [253, 141, 60, 170],
        [240, 59, 32, 212],
        [189, 0, 38, 255],
    ]

    self.call_js_method(
        "addHeatmapLayer",
        id=layer_id,
        data=processed_data,
        getPosition=get_position,
        getWeight=get_weight,
        radiusPixels=radius_pixels,
        intensity=intensity,
        threshold=threshold,
        colorRange=color_range or default_color_range,
        opacity=opacity,
        **kwargs,
    )

    self._deck_layers = {
        **self._deck_layers,
        layer_id: {"type": "HeatmapLayer", "id": layer_id},
    }

add_hexagon_layer(self, data, name=None, get_position='coordinates', radius=1000, elevation_scale=4, extruded=True, color_range=None, pickable=True, opacity=0.8, **kwargs)

Add a hexagon layer for hexbin aggregation visualization.

Parameters:

Name Type Description Default
data Any

Array of data objects with position coordinates.

required
name Optional[str]

Layer ID.

None
get_position Union[str, Callable]

Accessor for point position [lng, lat].

'coordinates'
radius float

Hexagon radius in meters.

1000
elevation_scale float

Elevation multiplier for 3D.

4
extruded bool

Whether to render as 3D hexagons.

True
color_range Optional[List[List[int]]]

Color gradient for aggregation [[r, g, b], ...].

None
pickable bool

Whether layer responds to hover/click.

True
opacity float

Layer opacity.

0.8
**kwargs

Additional layer props.

{}
Source code in anymap_ts/deckgl.py
def add_hexagon_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_position: Union[str, Callable] = "coordinates",
    radius: float = 1000,
    elevation_scale: float = 4,
    extruded: bool = True,
    color_range: Optional[List[List[int]]] = None,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add a hexagon layer for hexbin aggregation visualization.

    Args:
        data: Array of data objects with position coordinates.
        name: Layer ID.
        get_position: Accessor for point position [lng, lat].
        radius: Hexagon radius in meters.
        elevation_scale: Elevation multiplier for 3D.
        extruded: Whether to render as 3D hexagons.
        color_range: Color gradient for aggregation [[r, g, b], ...].
        pickable: Whether layer responds to hover/click.
        opacity: Layer opacity.
        **kwargs: Additional layer props.
    """
    layer_id = name or f"hexagon-{len(self._deck_layers)}"
    processed_data = self._process_deck_data(data)

    default_color_range = [
        [1, 152, 189],
        [73, 227, 206],
        [216, 254, 181],
        [254, 237, 177],
        [254, 173, 84],
        [209, 55, 78],
    ]

    self.call_js_method(
        "addHexagonLayer",
        id=layer_id,
        data=processed_data,
        getPosition=get_position,
        radius=radius,
        elevationScale=elevation_scale,
        extruded=extruded,
        colorRange=color_range or default_color_range,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._deck_layers = {
        **self._deck_layers,
        layer_id: {"type": "HexagonLayer", "id": layer_id},
    }

add_icon_layer(self, data, name=None, get_position='coordinates', get_icon='icon', get_size=20, get_color=None, icon_atlas=None, icon_mapping=None, pickable=True, opacity=1, **kwargs)

Add an icon layer for custom marker visualization.

Parameters:

Name Type Description Default
data Any

Array of data objects with position coordinates.

required
name Optional[str]

Layer ID.

None
get_position Union[str, Callable]

Accessor for icon position [lng, lat].

'coordinates'
get_icon Union[str, Callable]

Accessor for icon name in icon_mapping.

'icon'
get_size Union[float, str, Callable]

Accessor for icon size.

20
get_color Union[List[int], str, Callable]

Accessor for icon tint color [r, g, b, a].

None
icon_atlas Optional[str]

URL to icon atlas image.

None
icon_mapping Optional[Dict]

Dict mapping icon names to atlas coordinates.

None
pickable bool

Whether layer responds to hover/click.

True
opacity float

Layer opacity.

1
**kwargs

Additional layer props.

{}
Source code in anymap_ts/deckgl.py
def add_icon_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_position: Union[str, Callable] = "coordinates",
    get_icon: Union[str, Callable] = "icon",
    get_size: Union[float, str, Callable] = 20,
    get_color: Union[List[int], str, Callable] = None,
    icon_atlas: Optional[str] = None,
    icon_mapping: Optional[Dict] = None,
    pickable: bool = True,
    opacity: float = 1,
    **kwargs,
) -> None:
    """Add an icon layer for custom marker visualization.

    Args:
        data: Array of data objects with position coordinates.
        name: Layer ID.
        get_position: Accessor for icon position [lng, lat].
        get_icon: Accessor for icon name in icon_mapping.
        get_size: Accessor for icon size.
        get_color: Accessor for icon tint color [r, g, b, a].
        icon_atlas: URL to icon atlas image.
        icon_mapping: Dict mapping icon names to atlas coordinates.
        pickable: Whether layer responds to hover/click.
        opacity: Layer opacity.
        **kwargs: Additional layer props.
    """
    layer_id = name or f"icon-{len(self._deck_layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addIconLayer",
        id=layer_id,
        data=processed_data,
        getPosition=get_position,
        getIcon=get_icon,
        getSize=get_size,
        getColor=get_color or [255, 255, 255, 255],
        iconAtlas=icon_atlas,
        iconMapping=icon_mapping,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._deck_layers = {
        **self._deck_layers,
        layer_id: {"type": "IconLayer", "id": layer_id},
    }

add_line_layer(self, data, name=None, get_source_position='sourcePosition', get_target_position='targetPosition', get_color=None, get_width=1, width_min_pixels=1, pickable=True, opacity=0.8, **kwargs)

Add a line layer for simple line segment visualization.

The LineLayer renders straight line segments between source and target positions. Unlike ArcLayer, lines are drawn directly without curvature.

Parameters:

Name Type Description Default
data Any

Array of line objects with source/target positions.

required
name Optional[str]

Layer ID. If None, auto-generated.

None
get_source_position Union[str, Callable]

Accessor for source position [lng, lat].

'sourcePosition'
get_target_position Union[str, Callable]

Accessor for target position [lng, lat].

'targetPosition'
get_color Union[List[int], str, Callable]

Accessor for line color [r, g, b] or [r, g, b, a].

None
get_width Union[float, str, Callable]

Accessor for line width.

1
width_min_pixels float

Minimum line width in pixels.

1
pickable bool

Whether layer responds to hover/click.

True
opacity float

Layer opacity (0-1).

0.8
**kwargs

Additional LineLayer props.

{}

Examples:

>>> m = DeckGLMap()
>>> lines = [
...     {"sourcePosition": [-122.4, 37.8], "targetPosition": [-122.5, 37.7]},
...     {"sourcePosition": [-122.5, 37.7], "targetPosition": [-122.6, 37.8]},
... ]
>>> m.add_line_layer(
...     data=lines,
...     get_color=[0, 128, 255],
...     get_width=2,
... )
Source code in anymap_ts/deckgl.py
def add_line_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_source_position: Union[str, Callable] = "sourcePosition",
    get_target_position: Union[str, Callable] = "targetPosition",
    get_color: Union[List[int], str, Callable] = None,
    get_width: Union[float, str, Callable] = 1,
    width_min_pixels: float = 1,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add a line layer for simple line segment visualization.

    The LineLayer renders straight line segments between source and
    target positions. Unlike ArcLayer, lines are drawn directly
    without curvature.

    Args:
        data: Array of line objects with source/target positions.
        name: Layer ID. If None, auto-generated.
        get_source_position: Accessor for source position [lng, lat].
        get_target_position: Accessor for target position [lng, lat].
        get_color: Accessor for line color [r, g, b] or [r, g, b, a].
        get_width: Accessor for line width.
        width_min_pixels: Minimum line width in pixels.
        pickable: Whether layer responds to hover/click.
        opacity: Layer opacity (0-1).
        **kwargs: Additional LineLayer props.

    Example:
        >>> m = DeckGLMap()
        >>> lines = [
        ...     {"sourcePosition": [-122.4, 37.8], "targetPosition": [-122.5, 37.7]},
        ...     {"sourcePosition": [-122.5, 37.7], "targetPosition": [-122.6, 37.8]},
        ... ]
        >>> m.add_line_layer(
        ...     data=lines,
        ...     get_color=[0, 128, 255],
        ...     get_width=2,
        ... )
    """
    layer_id = name or f"line-{len(self._deck_layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addLineLayer",
        id=layer_id,
        data=processed_data,
        getSourcePosition=get_source_position,
        getTargetPosition=get_target_position,
        getColor=get_color or [51, 136, 255, 200],
        getWidth=get_width,
        widthMinPixels=width_min_pixels,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._deck_layers = {
        **self._deck_layers,
        layer_id: {"type": "LineLayer", "id": layer_id},
    }

add_mvt_layer(self, data, name=None, min_zoom=0, max_zoom=14, binary=True, get_fill_color=None, get_line_color=None, get_line_width=1, get_point_radius=5, line_width_min_pixels=1, point_radius_min_pixels=2, pickable=True, visible=True, opacity=1.0, **kwargs)

Add a Mapbox Vector Tile (MVT) layer.

Parameters:

Name Type Description Default
data Union[str, List[str]]

MVT tile URL template with {z}/{x}/{y} placeholders.

required
name Optional[str]

Layer ID.

None
min_zoom int

Minimum zoom level.

0
max_zoom int

Maximum zoom level.

14
binary bool

Whether to use binary format.

True
get_fill_color Union[List[int], str, Callable]

Accessor for fill color [r, g, b, a].

None
get_line_color Union[List[int], str, Callable]

Accessor for stroke color [r, g, b, a].

None
get_line_width Union[float, str, Callable]

Accessor for line width.

1
get_point_radius Union[float, str, Callable]

Accessor for point radius.

5
line_width_min_pixels float

Minimum line width in pixels.

1
point_radius_min_pixels float

Minimum point radius in pixels.

2
pickable bool

Whether layer responds to hover/click.

True
visible bool

Whether layer is visible.

True
opacity float

Layer opacity (0-1).

1.0
**kwargs

Additional MVTLayer props.

{}
Source code in anymap_ts/deckgl.py
def add_mvt_layer(
    self,
    data: Union[str, List[str]],
    name: Optional[str] = None,
    min_zoom: int = 0,
    max_zoom: int = 14,
    binary: bool = True,
    get_fill_color: Union[List[int], str, Callable] = None,
    get_line_color: Union[List[int], str, Callable] = None,
    get_line_width: Union[float, str, Callable] = 1,
    get_point_radius: Union[float, str, Callable] = 5,
    line_width_min_pixels: float = 1,
    point_radius_min_pixels: float = 2,
    pickable: bool = True,
    visible: bool = True,
    opacity: float = 1.0,
    **kwargs,
) -> None:
    """Add a Mapbox Vector Tile (MVT) layer.

    Args:
        data: MVT tile URL template with {z}/{x}/{y} placeholders.
        name: Layer ID.
        min_zoom: Minimum zoom level.
        max_zoom: Maximum zoom level.
        binary: Whether to use binary format.
        get_fill_color: Accessor for fill color [r, g, b, a].
        get_line_color: Accessor for stroke color [r, g, b, a].
        get_line_width: Accessor for line width.
        get_point_radius: Accessor for point radius.
        line_width_min_pixels: Minimum line width in pixels.
        point_radius_min_pixels: Minimum point radius in pixels.
        pickable: Whether layer responds to hover/click.
        visible: Whether layer is visible.
        opacity: Layer opacity (0-1).
        **kwargs: Additional MVTLayer props.
    """
    layer_id = name or f"mvt-{len(self._deck_layers)}"

    self.call_js_method(
        "addMVTLayer",
        id=layer_id,
        data=data,
        minZoom=min_zoom,
        maxZoom=max_zoom,
        binary=binary,
        getFillColor=get_fill_color or [51, 136, 255, 128],
        getLineColor=get_line_color or [0, 0, 0, 255],
        getLineWidth=get_line_width,
        getPointRadius=get_point_radius,
        lineWidthMinPixels=line_width_min_pixels,
        pointRadiusMinPixels=point_radius_min_pixels,
        pickable=pickable,
        visible=visible,
        opacity=opacity,
        **kwargs,
    )

    self._deck_layers = {
        **self._deck_layers,
        layer_id: {"type": "MVTLayer", "id": layer_id},
    }

add_path_layer(self, data, name=None, get_path='path', get_color=None, get_width=1, width_scale=1, width_min_pixels=1, pickable=True, opacity=0.8, **kwargs)

Add a path layer for polyline visualization.

Parameters:

Name Type Description Default
data Any

Array of data objects with path coordinates.

required
name Optional[str]

Layer ID.

None
get_path Union[str, Callable]

Accessor for path coordinates [[lng, lat], ...].

'path'
get_color Union[List[int], str, Callable]

Accessor for path color [r, g, b, a].

None
get_width Union[float, str, Callable]

Accessor for path width.

1
width_scale float

Global width multiplier.

1
width_min_pixels float

Minimum width in pixels.

1
pickable bool

Whether layer responds to hover/click.

True
opacity float

Layer opacity.

0.8
**kwargs

Additional layer props.

{}
Source code in anymap_ts/deckgl.py
def add_path_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_path: Union[str, Callable] = "path",
    get_color: Union[List[int], str, Callable] = None,
    get_width: Union[float, str, Callable] = 1,
    width_scale: float = 1,
    width_min_pixels: float = 1,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add a path layer for polyline visualization.

    Args:
        data: Array of data objects with path coordinates.
        name: Layer ID.
        get_path: Accessor for path coordinates [[lng, lat], ...].
        get_color: Accessor for path color [r, g, b, a].
        get_width: Accessor for path width.
        width_scale: Global width multiplier.
        width_min_pixels: Minimum width in pixels.
        pickable: Whether layer responds to hover/click.
        opacity: Layer opacity.
        **kwargs: Additional layer props.
    """
    layer_id = name or f"path-{len(self._deck_layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addPathLayer",
        id=layer_id,
        data=processed_data,
        getPath=get_path,
        getColor=get_color or [51, 136, 255, 200],
        getWidth=get_width,
        widthScale=width_scale,
        widthMinPixels=width_min_pixels,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._deck_layers = {
        **self._deck_layers,
        layer_id: {"type": "PathLayer", "id": layer_id},
    }

add_point_cloud_layer(self, data, name=None, get_position='position', get_color=None, get_normal=None, point_size=2, size_units='pixels', coordinate_system=None, coordinate_origin=None, pickable=True, opacity=1.0, **kwargs)

Add a point cloud layer for 3D point visualization.

Renders large point cloud datasets typically from LiDAR or 3D scanning. Supports both 2D and 3D coordinates with optional normal vectors for lighting effects.

Parameters:

Name Type Description Default
data Any

Array of point data with position [x, y, z] coordinates.

required
name Optional[str]

Layer ID. If None, auto-generated.

None
get_position Union[str, Callable]

Accessor for point position [x, y, z].

'position'
get_color Union[List[int], str, Callable]

Accessor for point color [r, g, b, a].

None
get_normal Union[str, Callable]

Accessor for point normal [nx, ny, nz] for lighting.

None
point_size float

Point size in size_units.

2
size_units str

Units for point_size ('pixels' or 'meters').

'pixels'
coordinate_system Optional[str]

Coordinate system ('CARTESIAN', 'METER_OFFSETS', 'LNGLAT', 'LNGLAT_OFFSETS').

None
coordinate_origin Optional[List[float]]

Origin for offset coordinate systems [lng, lat, z].

None
pickable bool

Whether layer responds to hover/click.

True
opacity float

Layer opacity (0-1).

1.0
**kwargs

Additional PointCloudLayer props.

{}

Examples:

>>> m = DeckGLMap()
>>> points = [
...     {"position": [-122.4, 37.8, 100], "color": [255, 0, 0]},
...     {"position": [-122.5, 37.7, 200], "color": [0, 255, 0]},
... ]
>>> m.add_point_cloud_layer(
...     data=points,
...     point_size=5,
...     get_color="color"
... )
Source code in anymap_ts/deckgl.py
def add_point_cloud_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_position: Union[str, Callable] = "position",
    get_color: Union[List[int], str, Callable] = None,
    get_normal: Union[str, Callable] = None,
    point_size: float = 2,
    size_units: str = "pixels",
    coordinate_system: Optional[str] = None,
    coordinate_origin: Optional[List[float]] = None,
    pickable: bool = True,
    opacity: float = 1.0,
    **kwargs,
) -> None:
    """Add a point cloud layer for 3D point visualization.

    Renders large point cloud datasets typically from LiDAR or 3D scanning.
    Supports both 2D and 3D coordinates with optional normal vectors for
    lighting effects.

    Args:
        data: Array of point data with position [x, y, z] coordinates.
        name: Layer ID. If None, auto-generated.
        get_position: Accessor for point position [x, y, z].
        get_color: Accessor for point color [r, g, b, a].
        get_normal: Accessor for point normal [nx, ny, nz] for lighting.
        point_size: Point size in size_units.
        size_units: Units for point_size ('pixels' or 'meters').
        coordinate_system: Coordinate system ('CARTESIAN', 'METER_OFFSETS',
            'LNGLAT', 'LNGLAT_OFFSETS').
        coordinate_origin: Origin for offset coordinate systems [lng, lat, z].
        pickable: Whether layer responds to hover/click.
        opacity: Layer opacity (0-1).
        **kwargs: Additional PointCloudLayer props.

    Example:
        >>> m = DeckGLMap()
        >>> points = [
        ...     {"position": [-122.4, 37.8, 100], "color": [255, 0, 0]},
        ...     {"position": [-122.5, 37.7, 200], "color": [0, 255, 0]},
        ... ]
        >>> m.add_point_cloud_layer(
        ...     data=points,
        ...     point_size=5,
        ...     get_color="color"
        ... )
    """
    layer_id = name or f"pointcloud-{len(self._deck_layers)}"
    processed_data = self._process_deck_data(data)

    layer_kwargs = {
        "id": layer_id,
        "data": processed_data,
        "getPosition": get_position,
        "getColor": get_color or [255, 255, 255, 255],
        "pointSize": point_size,
        "sizeUnits": size_units,
        "pickable": pickable,
        "opacity": opacity,
    }

    if get_normal is not None:
        layer_kwargs["getNormal"] = get_normal

    if coordinate_system is not None:
        layer_kwargs["coordinateSystem"] = coordinate_system

    if coordinate_origin is not None:
        layer_kwargs["coordinateOrigin"] = coordinate_origin

    layer_kwargs.update(kwargs)
    self.call_js_method("addPointCloudLayer", **layer_kwargs)

    self._deck_layers = {
        **self._deck_layers,
        layer_id: {"type": "PointCloudLayer", "id": layer_id},
    }

add_polygon_layer(self, data, name=None, get_polygon='polygon', get_fill_color=None, get_line_color=None, get_line_width=1, get_elevation=0, extruded=False, wireframe=False, filled=True, stroked=True, line_width_min_pixels=1, pickable=True, opacity=0.5, **kwargs)

Add a polygon layer for filled polygon visualization.

Parameters:

Name Type Description Default
data Any

Array of data objects with polygon coordinates.

required
name Optional[str]

Layer ID.

None
get_polygon Union[str, Callable]

Accessor for polygon coordinates.

'polygon'
get_fill_color Union[List[int], str, Callable]

Accessor for fill color [r, g, b, a].

None
get_line_color Union[List[int], str, Callable]

Accessor for stroke color [r, g, b, a].

None
get_line_width Union[float, str, Callable]

Accessor for stroke width.

1
get_elevation Union[float, str, Callable]

Accessor for 3D extrusion height.

0
extruded bool

Whether to render as 3D polygons.

False
wireframe bool

Whether to render wireframe (extruded only).

False
filled bool

Whether to fill polygons.

True
stroked bool

Whether to draw stroke.

True
line_width_min_pixels float

Minimum stroke width.

1
pickable bool

Whether layer responds to hover/click.

True
opacity float

Layer opacity.

0.5
**kwargs

Additional layer props.

{}
Source code in anymap_ts/deckgl.py
def add_polygon_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_polygon: Union[str, Callable] = "polygon",
    get_fill_color: Union[List[int], str, Callable] = None,
    get_line_color: Union[List[int], str, Callable] = None,
    get_line_width: Union[float, str, Callable] = 1,
    get_elevation: Union[float, str, Callable] = 0,
    extruded: bool = False,
    wireframe: bool = False,
    filled: bool = True,
    stroked: bool = True,
    line_width_min_pixels: float = 1,
    pickable: bool = True,
    opacity: float = 0.5,
    **kwargs,
) -> None:
    """Add a polygon layer for filled polygon visualization.

    Args:
        data: Array of data objects with polygon coordinates.
        name: Layer ID.
        get_polygon: Accessor for polygon coordinates.
        get_fill_color: Accessor for fill color [r, g, b, a].
        get_line_color: Accessor for stroke color [r, g, b, a].
        get_line_width: Accessor for stroke width.
        get_elevation: Accessor for 3D extrusion height.
        extruded: Whether to render as 3D polygons.
        wireframe: Whether to render wireframe (extruded only).
        filled: Whether to fill polygons.
        stroked: Whether to draw stroke.
        line_width_min_pixels: Minimum stroke width.
        pickable: Whether layer responds to hover/click.
        opacity: Layer opacity.
        **kwargs: Additional layer props.
    """
    layer_id = name or f"polygon-{len(self._deck_layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addPolygonLayer",
        id=layer_id,
        data=processed_data,
        getPolygon=get_polygon,
        getFillColor=get_fill_color or [51, 136, 255, 128],
        getLineColor=get_line_color or [0, 0, 255, 255],
        getLineWidth=get_line_width,
        getElevation=get_elevation,
        extruded=extruded,
        wireframe=wireframe,
        filled=filled,
        stroked=stroked,
        lineWidthMinPixels=line_width_min_pixels,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._deck_layers = {
        **self._deck_layers,
        layer_id: {"type": "PolygonLayer", "id": layer_id},
    }

add_quadkey_layer(self, data, name=None, get_quadkey='quadkey', get_fill_color=None, get_line_color=None, get_line_width=1, get_elevation=0, filled=True, stroked=True, extruded=False, wireframe=False, elevation_scale=1, pickable=True, opacity=0.8, **kwargs)

Add a Quadkey layer for Bing Maps tile index visualization.

Parameters:

Name Type Description Default
data Any

Array of data objects with quadkey.

required
name Optional[str]

Layer ID.

None
get_quadkey Union[str, Callable]

Accessor for quadkey string.

'quadkey'
get_fill_color Union[List[int], str, Callable]

Accessor for fill color [r, g, b, a].

None
get_line_color Union[List[int], str, Callable]

Accessor for stroke color [r, g, b, a].

None
get_line_width Union[float, str, Callable]

Accessor for line width.

1
get_elevation Union[float, str, Callable]

Accessor for 3D extrusion height.

0
filled bool

Whether to fill cells.

True
stroked bool

Whether to stroke cells.

True
extruded bool

Whether to render as 3D.

False
wireframe bool

Whether to render wireframe.

False
elevation_scale float

Elevation multiplier.

1
pickable bool

Whether layer responds to hover/click.

True
opacity float

Layer opacity.

0.8
**kwargs

Additional QuadkeyLayer props.

{}
Source code in anymap_ts/deckgl.py
def add_quadkey_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_quadkey: Union[str, Callable] = "quadkey",
    get_fill_color: Union[List[int], str, Callable] = None,
    get_line_color: Union[List[int], str, Callable] = None,
    get_line_width: Union[float, str, Callable] = 1,
    get_elevation: Union[float, str, Callable] = 0,
    filled: bool = True,
    stroked: bool = True,
    extruded: bool = False,
    wireframe: bool = False,
    elevation_scale: float = 1,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add a Quadkey layer for Bing Maps tile index visualization.

    Args:
        data: Array of data objects with quadkey.
        name: Layer ID.
        get_quadkey: Accessor for quadkey string.
        get_fill_color: Accessor for fill color [r, g, b, a].
        get_line_color: Accessor for stroke color [r, g, b, a].
        get_line_width: Accessor for line width.
        get_elevation: Accessor for 3D extrusion height.
        filled: Whether to fill cells.
        stroked: Whether to stroke cells.
        extruded: Whether to render as 3D.
        wireframe: Whether to render wireframe.
        elevation_scale: Elevation multiplier.
        pickable: Whether layer responds to hover/click.
        opacity: Layer opacity.
        **kwargs: Additional QuadkeyLayer props.
    """
    layer_id = name or f"quadkey-{len(self._deck_layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addQuadkeyLayer",
        id=layer_id,
        data=processed_data,
        getQuadkey=get_quadkey,
        getFillColor=get_fill_color or [51, 136, 255, 128],
        getLineColor=get_line_color or [0, 0, 0, 255],
        getLineWidth=get_line_width,
        getElevation=get_elevation,
        filled=filled,
        stroked=stroked,
        extruded=extruded,
        wireframe=wireframe,
        elevationScale=elevation_scale,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._deck_layers = {
        **self._deck_layers,
        layer_id: {"type": "QuadkeyLayer", "id": layer_id},
    }

add_s2_layer(self, data, name=None, get_s2_token='s2Token', get_fill_color=None, get_line_color=None, get_line_width=1, get_elevation=0, filled=True, stroked=True, extruded=False, wireframe=False, elevation_scale=1, pickable=True, opacity=0.8, **kwargs)

Add an S2 layer for S2 geometry cell visualization.

Parameters:

Name Type Description Default
data Any

Array of data objects with S2 token.

required
name Optional[str]

Layer ID.

None
get_s2_token Union[str, Callable]

Accessor for S2 token string.

's2Token'
get_fill_color Union[List[int], str, Callable]

Accessor for fill color [r, g, b, a].

None
get_line_color Union[List[int], str, Callable]

Accessor for stroke color [r, g, b, a].

None
get_line_width Union[float, str, Callable]

Accessor for line width.

1
get_elevation Union[float, str, Callable]

Accessor for 3D extrusion height.

0
filled bool

Whether to fill cells.

True
stroked bool

Whether to stroke cells.

True
extruded bool

Whether to render as 3D.

False
wireframe bool

Whether to render wireframe.

False
elevation_scale float

Elevation multiplier.

1
pickable bool

Whether layer responds to hover/click.

True
opacity float

Layer opacity.

0.8
**kwargs

Additional S2Layer props.

{}
Source code in anymap_ts/deckgl.py
def add_s2_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_s2_token: Union[str, Callable] = "s2Token",
    get_fill_color: Union[List[int], str, Callable] = None,
    get_line_color: Union[List[int], str, Callable] = None,
    get_line_width: Union[float, str, Callable] = 1,
    get_elevation: Union[float, str, Callable] = 0,
    filled: bool = True,
    stroked: bool = True,
    extruded: bool = False,
    wireframe: bool = False,
    elevation_scale: float = 1,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add an S2 layer for S2 geometry cell visualization.

    Args:
        data: Array of data objects with S2 token.
        name: Layer ID.
        get_s2_token: Accessor for S2 token string.
        get_fill_color: Accessor for fill color [r, g, b, a].
        get_line_color: Accessor for stroke color [r, g, b, a].
        get_line_width: Accessor for line width.
        get_elevation: Accessor for 3D extrusion height.
        filled: Whether to fill cells.
        stroked: Whether to stroke cells.
        extruded: Whether to render as 3D.
        wireframe: Whether to render wireframe.
        elevation_scale: Elevation multiplier.
        pickable: Whether layer responds to hover/click.
        opacity: Layer opacity.
        **kwargs: Additional S2Layer props.
    """
    layer_id = name or f"s2-{len(self._deck_layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addS2Layer",
        id=layer_id,
        data=processed_data,
        getS2Token=get_s2_token,
        getFillColor=get_fill_color or [51, 136, 255, 128],
        getLineColor=get_line_color or [0, 0, 0, 255],
        getLineWidth=get_line_width,
        getElevation=get_elevation,
        filled=filled,
        stroked=stroked,
        extruded=extruded,
        wireframe=wireframe,
        elevationScale=elevation_scale,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._deck_layers = {
        **self._deck_layers,
        layer_id: {"type": "S2Layer", "id": layer_id},
    }

add_scatterplot_layer(self, data, name=None, get_position='coordinates', get_radius=5, get_fill_color=None, get_line_color=None, radius_scale=1, radius_min_pixels=1, radius_max_pixels=100, line_width_min_pixels=1, stroked=True, filled=True, pickable=True, opacity=0.8, **kwargs)

Add a scatterplot layer for point visualization.

Parameters:

Name Type Description Default
data Any

Array of data objects or GeoJSON.

required
name Optional[str]

Layer ID.

None
get_position Union[str, Callable]

Accessor for point position [lng, lat].

'coordinates'
get_radius Union[float, str, Callable]

Accessor for point radius.

5
get_fill_color Union[List[int], str, Callable]

Accessor for fill color [r, g, b, a].

None
get_line_color Union[List[int], str, Callable]

Accessor for stroke color [r, g, b, a].

None
radius_scale float

Global radius multiplier.

1
radius_min_pixels float

Minimum radius in pixels.

1
radius_max_pixels float

Maximum radius in pixels.

100
line_width_min_pixels float

Minimum stroke width.

1
stroked bool

Whether to draw stroke.

True
filled bool

Whether to fill points.

True
pickable bool

Whether layer responds to hover/click.

True
opacity float

Layer opacity.

0.8
**kwargs

Additional layer props.

{}
Source code in anymap_ts/deckgl.py
def add_scatterplot_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_position: Union[str, Callable] = "coordinates",
    get_radius: Union[float, str, Callable] = 5,
    get_fill_color: Union[List[int], str, Callable] = None,
    get_line_color: Union[List[int], str, Callable] = None,
    radius_scale: float = 1,
    radius_min_pixels: float = 1,
    radius_max_pixels: float = 100,
    line_width_min_pixels: float = 1,
    stroked: bool = True,
    filled: bool = True,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add a scatterplot layer for point visualization.

    Args:
        data: Array of data objects or GeoJSON.
        name: Layer ID.
        get_position: Accessor for point position [lng, lat].
        get_radius: Accessor for point radius.
        get_fill_color: Accessor for fill color [r, g, b, a].
        get_line_color: Accessor for stroke color [r, g, b, a].
        radius_scale: Global radius multiplier.
        radius_min_pixels: Minimum radius in pixels.
        radius_max_pixels: Maximum radius in pixels.
        line_width_min_pixels: Minimum stroke width.
        stroked: Whether to draw stroke.
        filled: Whether to fill points.
        pickable: Whether layer responds to hover/click.
        opacity: Layer opacity.
        **kwargs: Additional layer props.
    """
    layer_id = name or f"scatterplot-{len(self._deck_layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addScatterplotLayer",
        id=layer_id,
        data=processed_data,
        getPosition=get_position,
        getRadius=get_radius,
        getFillColor=get_fill_color or [51, 136, 255, 200],
        getLineColor=get_line_color or [255, 255, 255, 255],
        radiusScale=radius_scale,
        radiusMinPixels=radius_min_pixels,
        radiusMaxPixels=radius_max_pixels,
        lineWidthMinPixels=line_width_min_pixels,
        stroked=stroked,
        filled=filled,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._deck_layers = {
        **self._deck_layers,
        layer_id: {"type": "ScatterplotLayer", "id": layer_id},
    }

add_scenegraph_layer(self, data, scenegraph, name=None, get_position='coordinates', get_color=None, get_orientation=None, get_scale=None, get_translation=None, size_scale=1, size_min_pixels=0, size_max_pixels=10000, pickable=True, opacity=1.0, **kwargs)

Add a scenegraph layer for glTF model visualization.

Parameters:

Name Type Description Default
data Any

Array of data objects with position coordinates.

required
scenegraph str

URL to glTF/GLB model file.

required
name Optional[str]

Layer ID.

None
get_position Union[str, Callable]

Accessor for model position [lng, lat, z].

'coordinates'
get_color Union[List[int], str, Callable]

Accessor for model tint color [r, g, b, a].

None
get_orientation Union[str, Callable]

Accessor for model orientation [pitch, yaw, roll].

None
get_scale Union[str, Callable]

Accessor for model scale [x, y, z].

None
get_translation Union[str, Callable]

Accessor for model translation [x, y, z].

None
size_scale float

Global size multiplier.

1
size_min_pixels float

Minimum model size in pixels.

0
size_max_pixels float

Maximum model size in pixels.

10000
pickable bool

Whether layer responds to hover/click.

True
opacity float

Layer opacity (0-1).

1.0
**kwargs

Additional ScenegraphLayer props.

{}
Source code in anymap_ts/deckgl.py
def add_scenegraph_layer(
    self,
    data: Any,
    scenegraph: str,
    name: Optional[str] = None,
    get_position: Union[str, Callable] = "coordinates",
    get_color: Union[List[int], str, Callable] = None,
    get_orientation: Union[str, Callable] = None,
    get_scale: Union[str, Callable] = None,
    get_translation: Union[str, Callable] = None,
    size_scale: float = 1,
    size_min_pixels: float = 0,
    size_max_pixels: float = 10000,
    pickable: bool = True,
    opacity: float = 1.0,
    **kwargs,
) -> None:
    """Add a scenegraph layer for glTF model visualization.

    Args:
        data: Array of data objects with position coordinates.
        scenegraph: URL to glTF/GLB model file.
        name: Layer ID.
        get_position: Accessor for model position [lng, lat, z].
        get_color: Accessor for model tint color [r, g, b, a].
        get_orientation: Accessor for model orientation [pitch, yaw, roll].
        get_scale: Accessor for model scale [x, y, z].
        get_translation: Accessor for model translation [x, y, z].
        size_scale: Global size multiplier.
        size_min_pixels: Minimum model size in pixels.
        size_max_pixels: Maximum model size in pixels.
        pickable: Whether layer responds to hover/click.
        opacity: Layer opacity (0-1).
        **kwargs: Additional ScenegraphLayer props.
    """
    layer_id = name or f"scenegraph-{len(self._deck_layers)}"
    processed_data = self._process_deck_data(data)

    layer_kwargs = {
        "id": layer_id,
        "data": processed_data,
        "scenegraph": scenegraph,
        "getPosition": get_position,
        "getColor": get_color or [255, 255, 255, 255],
        "sizeScale": size_scale,
        "sizeMinPixels": size_min_pixels,
        "sizeMaxPixels": size_max_pixels,
        "pickable": pickable,
        "opacity": opacity,
    }

    if get_orientation:
        layer_kwargs["getOrientation"] = get_orientation
    if get_scale:
        layer_kwargs["getScale"] = get_scale
    if get_translation:
        layer_kwargs["getTranslation"] = get_translation

    layer_kwargs.update(kwargs)
    self.call_js_method("addScenegraphLayer", **layer_kwargs)

    self._deck_layers = {
        **self._deck_layers,
        layer_id: {"type": "ScenegraphLayer", "id": layer_id},
    }

add_screen_grid_layer(self, data, name=None, get_position='coordinates', get_weight=1, cell_size_pixels=50, color_range=None, pickable=True, opacity=0.8, **kwargs)

Add a screen grid layer for screen-space grid aggregation.

Parameters:

Name Type Description Default
data Any

Array of data objects with position coordinates.

required
name Optional[str]

Layer ID.

None
get_position Union[str, Callable]

Accessor for point position [lng, lat].

'coordinates'
get_weight Union[float, str, Callable]

Accessor for point weight.

1
cell_size_pixels float

Grid cell size in pixels.

50
color_range Optional[List[List[int]]]

Color gradient [[r, g, b, a], ...].

None
pickable bool

Whether layer responds to hover/click.

True
opacity float

Layer opacity.

0.8
**kwargs

Additional layer props.

{}
Source code in anymap_ts/deckgl.py
def add_screen_grid_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_position: Union[str, Callable] = "coordinates",
    get_weight: Union[float, str, Callable] = 1,
    cell_size_pixels: float = 50,
    color_range: Optional[List[List[int]]] = None,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add a screen grid layer for screen-space grid aggregation.

    Args:
        data: Array of data objects with position coordinates.
        name: Layer ID.
        get_position: Accessor for point position [lng, lat].
        get_weight: Accessor for point weight.
        cell_size_pixels: Grid cell size in pixels.
        color_range: Color gradient [[r, g, b, a], ...].
        pickable: Whether layer responds to hover/click.
        opacity: Layer opacity.
        **kwargs: Additional layer props.
    """
    layer_id = name or f"screengrid-{len(self._deck_layers)}"
    processed_data = self._process_deck_data(data)

    default_color_range = [
        [255, 255, 178, 25],
        [254, 217, 118, 85],
        [254, 178, 76, 127],
        [253, 141, 60, 170],
        [240, 59, 32, 212],
        [189, 0, 38, 255],
    ]

    self.call_js_method(
        "addScreenGridLayer",
        id=layer_id,
        data=processed_data,
        getPosition=get_position,
        getWeight=get_weight,
        cellSizePixels=cell_size_pixels,
        colorRange=color_range or default_color_range,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._deck_layers = {
        **self._deck_layers,
        layer_id: {"type": "ScreenGridLayer", "id": layer_id},
    }

add_simple_mesh_layer(self, data, mesh, name=None, texture=None, get_position='coordinates', get_color=None, get_orientation=None, get_scale=None, get_translation=None, size_scale=1, wireframe=False, pickable=True, opacity=1.0, **kwargs)

Add a simple mesh layer for 3D mesh visualization.

Parameters:

Name Type Description Default
data Any

Array of data objects with position coordinates.

required
mesh str

URL to OBJ/glTF mesh file.

required
name Optional[str]

Layer ID.

None
texture Optional[str]

URL to texture image.

None
get_position Union[str, Callable]

Accessor for mesh position [lng, lat, z].

'coordinates'
get_color Union[List[int], str, Callable]

Accessor for mesh color [r, g, b, a].

None
get_orientation Union[str, Callable]

Accessor for mesh orientation [pitch, yaw, roll].

None
get_scale Union[str, Callable]

Accessor for mesh scale [x, y, z].

None
get_translation Union[str, Callable]

Accessor for mesh translation [x, y, z].

None
size_scale float

Global size multiplier.

1
wireframe bool

Whether to render as wireframe.

False
pickable bool

Whether layer responds to hover/click.

True
opacity float

Layer opacity (0-1).

1.0
**kwargs

Additional SimpleMeshLayer props.

{}
Source code in anymap_ts/deckgl.py
def add_simple_mesh_layer(
    self,
    data: Any,
    mesh: str,
    name: Optional[str] = None,
    texture: Optional[str] = None,
    get_position: Union[str, Callable] = "coordinates",
    get_color: Union[List[int], str, Callable] = None,
    get_orientation: Union[str, Callable] = None,
    get_scale: Union[str, Callable] = None,
    get_translation: Union[str, Callable] = None,
    size_scale: float = 1,
    wireframe: bool = False,
    pickable: bool = True,
    opacity: float = 1.0,
    **kwargs,
) -> None:
    """Add a simple mesh layer for 3D mesh visualization.

    Args:
        data: Array of data objects with position coordinates.
        mesh: URL to OBJ/glTF mesh file.
        name: Layer ID.
        texture: URL to texture image.
        get_position: Accessor for mesh position [lng, lat, z].
        get_color: Accessor for mesh color [r, g, b, a].
        get_orientation: Accessor for mesh orientation [pitch, yaw, roll].
        get_scale: Accessor for mesh scale [x, y, z].
        get_translation: Accessor for mesh translation [x, y, z].
        size_scale: Global size multiplier.
        wireframe: Whether to render as wireframe.
        pickable: Whether layer responds to hover/click.
        opacity: Layer opacity (0-1).
        **kwargs: Additional SimpleMeshLayer props.
    """
    layer_id = name or f"simplemesh-{len(self._deck_layers)}"
    processed_data = self._process_deck_data(data)

    layer_kwargs = {
        "id": layer_id,
        "data": processed_data,
        "mesh": mesh,
        "getPosition": get_position,
        "getColor": get_color or [255, 255, 255, 255],
        "sizeScale": size_scale,
        "wireframe": wireframe,
        "pickable": pickable,
        "opacity": opacity,
    }

    if texture:
        layer_kwargs["texture"] = texture
    if get_orientation:
        layer_kwargs["getOrientation"] = get_orientation
    if get_scale:
        layer_kwargs["getScale"] = get_scale
    if get_translation:
        layer_kwargs["getTranslation"] = get_translation

    layer_kwargs.update(kwargs)
    self.call_js_method("addSimpleMeshLayer", **layer_kwargs)

    self._deck_layers = {
        **self._deck_layers,
        layer_id: {"type": "SimpleMeshLayer", "id": layer_id},
    }

add_solid_polygon_layer(self, data, name=None, get_polygon='polygon', get_fill_color=None, get_line_color=None, get_elevation=0, filled=True, extruded=False, wireframe=False, elevation_scale=1, pickable=True, opacity=0.8, **kwargs)

Add a solid polygon layer for filled polygon visualization.

Parameters:

Name Type Description Default
data Any

Array of data objects with polygon coordinates.

required
name Optional[str]

Layer ID.

None
get_polygon Union[str, Callable]

Accessor for polygon coordinates.

'polygon'
get_fill_color Union[List[int], str, Callable]

Accessor for fill color [r, g, b, a].

None
get_line_color Union[List[int], str, Callable]

Accessor for stroke color [r, g, b, a].

None
get_elevation Union[float, str, Callable]

Accessor for 3D extrusion height.

0
filled bool

Whether to fill polygons.

True
extruded bool

Whether to render as 3D polygons.

False
wireframe bool

Whether to render wireframe.

False
elevation_scale float

Elevation multiplier.

1
pickable bool

Whether layer responds to hover/click.

True
opacity float

Layer opacity.

0.8
**kwargs

Additional SolidPolygonLayer props.

{}
Source code in anymap_ts/deckgl.py
def add_solid_polygon_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_polygon: Union[str, Callable] = "polygon",
    get_fill_color: Union[List[int], str, Callable] = None,
    get_line_color: Union[List[int], str, Callable] = None,
    get_elevation: Union[float, str, Callable] = 0,
    filled: bool = True,
    extruded: bool = False,
    wireframe: bool = False,
    elevation_scale: float = 1,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add a solid polygon layer for filled polygon visualization.

    Args:
        data: Array of data objects with polygon coordinates.
        name: Layer ID.
        get_polygon: Accessor for polygon coordinates.
        get_fill_color: Accessor for fill color [r, g, b, a].
        get_line_color: Accessor for stroke color [r, g, b, a].
        get_elevation: Accessor for 3D extrusion height.
        filled: Whether to fill polygons.
        extruded: Whether to render as 3D polygons.
        wireframe: Whether to render wireframe.
        elevation_scale: Elevation multiplier.
        pickable: Whether layer responds to hover/click.
        opacity: Layer opacity.
        **kwargs: Additional SolidPolygonLayer props.
    """
    layer_id = name or f"solidpolygon-{len(self._deck_layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addSolidPolygonLayer",
        id=layer_id,
        data=processed_data,
        getPolygon=get_polygon,
        getFillColor=get_fill_color or [51, 136, 255, 128],
        getLineColor=get_line_color or [0, 0, 0, 255],
        getElevation=get_elevation,
        filled=filled,
        extruded=extruded,
        wireframe=wireframe,
        elevationScale=elevation_scale,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._deck_layers = {
        **self._deck_layers,
        layer_id: {"type": "SolidPolygonLayer", "id": layer_id},
    }

add_terrain_layer(self, elevation_data, name=None, texture=None, mesh_max_error=4.0, bounds=None, elevation_decoder=None, pickable=False, visible=True, opacity=1.0, wireframe=False, **kwargs)

Add a terrain layer for 3D terrain visualization.

Parameters:

Name Type Description Default
elevation_data Union[str, List[str]]

URL to elevation tiles (e.g., Mapbox terrain).

required
name Optional[str]

Layer ID.

None
texture Optional[str]

URL to texture tiles for terrain surface.

None
mesh_max_error float

Maximum mesh error in meters.

4.0
bounds Optional[List[float]]

Bounding box [west, south, east, north].

None
elevation_decoder Optional[Dict]

Decoder for elevation data format.

None
pickable bool

Whether layer responds to hover/click.

False
visible bool

Whether layer is visible.

True
opacity float

Layer opacity (0-1).

1.0
wireframe bool

Whether to render as wireframe.

False
**kwargs

Additional TerrainLayer props.

{}
Source code in anymap_ts/deckgl.py
def add_terrain_layer(
    self,
    elevation_data: Union[str, List[str]],
    name: Optional[str] = None,
    texture: Optional[str] = None,
    mesh_max_error: float = 4.0,
    bounds: Optional[List[float]] = None,
    elevation_decoder: Optional[Dict] = None,
    pickable: bool = False,
    visible: bool = True,
    opacity: float = 1.0,
    wireframe: bool = False,
    **kwargs,
) -> None:
    """Add a terrain layer for 3D terrain visualization.

    Args:
        elevation_data: URL to elevation tiles (e.g., Mapbox terrain).
        name: Layer ID.
        texture: URL to texture tiles for terrain surface.
        mesh_max_error: Maximum mesh error in meters.
        bounds: Bounding box [west, south, east, north].
        elevation_decoder: Decoder for elevation data format.
        pickable: Whether layer responds to hover/click.
        visible: Whether layer is visible.
        opacity: Layer opacity (0-1).
        wireframe: Whether to render as wireframe.
        **kwargs: Additional TerrainLayer props.
    """
    layer_id = name or f"terrain-{len(self._deck_layers)}"

    default_decoder = {
        "rScaler": 256,
        "gScaler": 1,
        "bScaler": 1 / 256,
        "offset": -32768,
    }

    self.call_js_method(
        "addTerrainLayer",
        id=layer_id,
        elevationData=elevation_data,
        texture=texture,
        meshMaxError=mesh_max_error,
        bounds=bounds,
        elevationDecoder=elevation_decoder or default_decoder,
        pickable=pickable,
        visible=visible,
        opacity=opacity,
        wireframe=wireframe,
        **kwargs,
    )

    self._deck_layers = {
        **self._deck_layers,
        layer_id: {"type": "TerrainLayer", "id": layer_id},
    }

add_text_layer(self, data, name=None, get_position='coordinates', get_text='text', get_size=12, get_color=None, get_angle=0, text_anchor='middle', alignment_baseline='center', pickable=True, opacity=1, **kwargs)

Add a text layer for label visualization.

Parameters:

Name Type Description Default
data Any

Array of data objects with position and text.

required
name Optional[str]

Layer ID.

None
get_position Union[str, Callable]

Accessor for text position [lng, lat].

'coordinates'
get_text Union[str, Callable]

Accessor for text content.

'text'
get_size Union[float, str, Callable]

Accessor for text size.

12
get_color Union[List[int], str, Callable]

Accessor for text color [r, g, b, a].

None
get_angle Union[float, str, Callable]

Accessor for text rotation in degrees.

0
text_anchor str

Horizontal alignment ('start', 'middle', 'end').

'middle'
alignment_baseline str

Vertical alignment ('top', 'center', 'bottom').

'center'
pickable bool

Whether layer responds to hover/click.

True
opacity float

Layer opacity.

1
**kwargs

Additional layer props.

{}
Source code in anymap_ts/deckgl.py
def add_text_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_position: Union[str, Callable] = "coordinates",
    get_text: Union[str, Callable] = "text",
    get_size: Union[float, str, Callable] = 12,
    get_color: Union[List[int], str, Callable] = None,
    get_angle: Union[float, str, Callable] = 0,
    text_anchor: str = "middle",
    alignment_baseline: str = "center",
    pickable: bool = True,
    opacity: float = 1,
    **kwargs,
) -> None:
    """Add a text layer for label visualization.

    Args:
        data: Array of data objects with position and text.
        name: Layer ID.
        get_position: Accessor for text position [lng, lat].
        get_text: Accessor for text content.
        get_size: Accessor for text size.
        get_color: Accessor for text color [r, g, b, a].
        get_angle: Accessor for text rotation in degrees.
        text_anchor: Horizontal alignment ('start', 'middle', 'end').
        alignment_baseline: Vertical alignment ('top', 'center', 'bottom').
        pickable: Whether layer responds to hover/click.
        opacity: Layer opacity.
        **kwargs: Additional layer props.
    """
    layer_id = name or f"text-{len(self._deck_layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addTextLayer",
        id=layer_id,
        data=processed_data,
        getPosition=get_position,
        getText=get_text,
        getSize=get_size,
        getColor=get_color or [0, 0, 0, 255],
        getAngle=get_angle,
        getTextAnchor=text_anchor,
        getAlignmentBaseline=alignment_baseline,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._deck_layers = {
        **self._deck_layers,
        layer_id: {"type": "TextLayer", "id": layer_id},
    }

add_tile3d_layer(self, data, name=None, point_size=1, pickable=True, visible=True, opacity=1.0, load_options=None, **kwargs)

Add a 3D Tiles layer for 3D building/terrain visualization.

Parameters:

Name Type Description Default
data str

URL to tileset.json.

required
name Optional[str]

Layer ID.

None
point_size float

Point size for point cloud tiles.

1
pickable bool

Whether layer responds to hover/click.

True
visible bool

Whether layer is visible.

True
opacity float

Layer opacity (0-1).

1.0
load_options Optional[Dict]

Loader options for tile loading.

None
**kwargs

Additional Tile3DLayer props.

{}
Source code in anymap_ts/deckgl.py
def add_tile3d_layer(
    self,
    data: str,
    name: Optional[str] = None,
    point_size: float = 1,
    pickable: bool = True,
    visible: bool = True,
    opacity: float = 1.0,
    load_options: Optional[Dict] = None,
    **kwargs,
) -> None:
    """Add a 3D Tiles layer for 3D building/terrain visualization.

    Args:
        data: URL to tileset.json.
        name: Layer ID.
        point_size: Point size for point cloud tiles.
        pickable: Whether layer responds to hover/click.
        visible: Whether layer is visible.
        opacity: Layer opacity (0-1).
        load_options: Loader options for tile loading.
        **kwargs: Additional Tile3DLayer props.
    """
    layer_id = name or f"tile3d-{len(self._deck_layers)}"

    self.call_js_method(
        "addTile3DLayer",
        id=layer_id,
        data=data,
        pointSize=point_size,
        pickable=pickable,
        visible=visible,
        opacity=opacity,
        loadOptions=load_options or {},
        **kwargs,
    )

    self._deck_layers = {
        **self._deck_layers,
        layer_id: {"type": "Tile3DLayer", "id": layer_id},
    }

add_tile_layer(self, data, name=None, min_zoom=0, max_zoom=19, tile_size=256, pickable=False, visible=True, opacity=1.0, **kwargs)

Add a tile layer for raster tile visualization.

Parameters:

Name Type Description Default
data Union[str, List[str]]

Tile URL template with {z}/{x}/{y} placeholders.

required
name Optional[str]

Layer ID.

None
min_zoom int

Minimum zoom level.

0
max_zoom int

Maximum zoom level.

19
tile_size int

Tile size in pixels.

256
pickable bool

Whether layer responds to hover/click.

False
visible bool

Whether layer is visible.

True
opacity float

Layer opacity (0-1).

1.0
**kwargs

Additional TileLayer props.

{}
Source code in anymap_ts/deckgl.py
def add_tile_layer(
    self,
    data: Union[str, List[str]],
    name: Optional[str] = None,
    min_zoom: int = 0,
    max_zoom: int = 19,
    tile_size: int = 256,
    pickable: bool = False,
    visible: bool = True,
    opacity: float = 1.0,
    **kwargs,
) -> None:
    """Add a tile layer for raster tile visualization.

    Args:
        data: Tile URL template with {z}/{x}/{y} placeholders.
        name: Layer ID.
        min_zoom: Minimum zoom level.
        max_zoom: Maximum zoom level.
        tile_size: Tile size in pixels.
        pickable: Whether layer responds to hover/click.
        visible: Whether layer is visible.
        opacity: Layer opacity (0-1).
        **kwargs: Additional TileLayer props.
    """
    layer_id = name or f"tile-{len(self._deck_layers)}"

    self.call_js_method(
        "addTileLayer",
        id=layer_id,
        data=data,
        minZoom=min_zoom,
        maxZoom=max_zoom,
        tileSize=tile_size,
        pickable=pickable,
        visible=visible,
        opacity=opacity,
        **kwargs,
    )

    self._deck_layers = {
        **self._deck_layers,
        layer_id: {"type": "TileLayer", "id": layer_id},
    }

add_trips_layer(self, data, name=None, get_path='waypoints', get_timestamps='timestamps', get_color=None, width_min_pixels=2, trail_length=180, current_time=0, pickable=True, opacity=0.8, **kwargs)

Add a trips layer for animated path visualization.

The TripsLayer renders animated paths showing movement over time, ideal for visualizing vehicle routes, migration patterns, or any time-based trajectory data.

Parameters:

Name Type Description Default
data Any

Array of trip objects with waypoints and timestamps.

required
name Optional[str]

Layer ID. If None, auto-generated.

None
get_path Union[str, Callable]

Accessor for waypoint coordinates [[lng, lat], ...].

'waypoints'
get_timestamps Union[str, Callable]

Accessor for timestamps at each waypoint.

'timestamps'
get_color Union[List[int], str, Callable]

Accessor for trip color [r, g, b] or [r, g, b, a].

None
width_min_pixels float

Minimum trail width in pixels.

2
trail_length float

Trail length in timestamp units.

180
current_time float

Current animation time.

0
pickable bool

Whether layer responds to hover/click.

True
opacity float

Layer opacity (0-1).

0.8
**kwargs

Additional TripsLayer props.

{}

Examples:

>>> m = DeckGLMap()
>>> trips = [
...     {
...         "waypoints": [[-122.4, 37.8], [-122.5, 37.7], [-122.6, 37.8]],
...         "timestamps": [0, 50, 100]
...     }
... ]
>>> m.add_trips_layer(
...     data=trips,
...     trail_length=180,
...     current_time=50,
... )
Source code in anymap_ts/deckgl.py
def add_trips_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_path: Union[str, Callable] = "waypoints",
    get_timestamps: Union[str, Callable] = "timestamps",
    get_color: Union[List[int], str, Callable] = None,
    width_min_pixels: float = 2,
    trail_length: float = 180,
    current_time: float = 0,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add a trips layer for animated path visualization.

    The TripsLayer renders animated paths showing movement over time,
    ideal for visualizing vehicle routes, migration patterns, or any
    time-based trajectory data.

    Args:
        data: Array of trip objects with waypoints and timestamps.
        name: Layer ID. If None, auto-generated.
        get_path: Accessor for waypoint coordinates [[lng, lat], ...].
        get_timestamps: Accessor for timestamps at each waypoint.
        get_color: Accessor for trip color [r, g, b] or [r, g, b, a].
        width_min_pixels: Minimum trail width in pixels.
        trail_length: Trail length in timestamp units.
        current_time: Current animation time.
        pickable: Whether layer responds to hover/click.
        opacity: Layer opacity (0-1).
        **kwargs: Additional TripsLayer props.

    Example:
        >>> m = DeckGLMap()
        >>> trips = [
        ...     {
        ...         "waypoints": [[-122.4, 37.8], [-122.5, 37.7], [-122.6, 37.8]],
        ...         "timestamps": [0, 50, 100]
        ...     }
        ... ]
        >>> m.add_trips_layer(
        ...     data=trips,
        ...     trail_length=180,
        ...     current_time=50,
        ... )
    """
    layer_id = name or f"trips-{len(self._deck_layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addTripsLayer",
        id=layer_id,
        data=processed_data,
        getPath=get_path,
        getTimestamps=get_timestamps,
        getColor=get_color or [253, 128, 93],
        widthMinPixels=width_min_pixels,
        trailLength=trail_length,
        currentTime=current_time,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._deck_layers = {
        **self._deck_layers,
        layer_id: {"type": "TripsLayer", "id": layer_id},
    }

add_wms_layer(self, data, name=None, service_type='wms', layers=None, srs=None, pickable=False, visible=True, opacity=1.0, **kwargs)

Add a WMS layer for OGC Web Map Service visualization.

Parameters:

Name Type Description Default
data str

WMS base URL.

required
name Optional[str]

Layer ID.

None
service_type str

Service type ('wms' or 'template').

'wms'
layers Optional[List[str]]

WMS layer names to request.

None
srs Optional[str]

Spatial reference system (e.g., 'EPSG:4326').

None
pickable bool

Whether layer responds to hover/click.

False
visible bool

Whether layer is visible.

True
opacity float

Layer opacity (0-1).

1.0
**kwargs

Additional WMSLayer props.

{}
Source code in anymap_ts/deckgl.py
def add_wms_layer(
    self,
    data: str,
    name: Optional[str] = None,
    service_type: str = "wms",
    layers: Optional[List[str]] = None,
    srs: Optional[str] = None,
    pickable: bool = False,
    visible: bool = True,
    opacity: float = 1.0,
    **kwargs,
) -> None:
    """Add a WMS layer for OGC Web Map Service visualization.

    Args:
        data: WMS base URL.
        name: Layer ID.
        service_type: Service type ('wms' or 'template').
        layers: WMS layer names to request.
        srs: Spatial reference system (e.g., 'EPSG:4326').
        pickable: Whether layer responds to hover/click.
        visible: Whether layer is visible.
        opacity: Layer opacity (0-1).
        **kwargs: Additional WMSLayer props.
    """
    layer_id = name or f"wms-{len(self._deck_layers)}"

    self.call_js_method(
        "addWMSLayer",
        id=layer_id,
        data=data,
        serviceType=service_type,
        layers=layers,
        srs=srs,
        pickable=pickable,
        visible=visible,
        opacity=opacity,
        **kwargs,
    )

    self._deck_layers = {
        **self._deck_layers,
        layer_id: {"type": "WMSLayer", "id": layer_id},
    }

remove_cog_layer(self, layer_id)

Remove a COG layer.

Parameters:

Name Type Description Default
layer_id str

Layer identifier to remove.

required
Source code in anymap_ts/deckgl.py
def remove_cog_layer(self, layer_id: str) -> None:
    """Remove a COG layer.

    Args:
        layer_id: Layer identifier to remove.
    """
    self.remove_deck_layer(layer_id)

remove_deck_layer(self, layer_id)

Remove a deck.gl layer.

Parameters:

Name Type Description Default
layer_id str

Layer identifier to remove.

required
Source code in anymap_ts/deckgl.py
def remove_deck_layer(self, layer_id: str) -> None:
    """Remove a deck.gl layer.

    Args:
        layer_id: Layer identifier to remove.
    """
    if layer_id in self._deck_layers:
        layers = dict(self._deck_layers)
        del layers[layer_id]
        self._deck_layers = layers
    self.call_js_method("removeDeckLayer", layer_id)

set_deck_layer_visibility(self, layer_id, visible)

Set deck.gl layer visibility.

Parameters:

Name Type Description Default
layer_id str

Layer identifier.

required
visible bool

Whether layer should be visible.

required
Source code in anymap_ts/deckgl.py
def set_deck_layer_visibility(self, layer_id: str, visible: bool) -> None:
    """Set deck.gl layer visibility.

    Args:
        layer_id: Layer identifier.
        visible: Whether layer should be visible.
    """
    self.call_js_method("setDeckLayerVisibility", layer_id, visible)

keplergl

KeplerGL map widget implementation.

KeplerGL is loaded via CDN since it's React-based and requires complex setup. This implementation provides a Python wrapper with data management capabilities.

KeplerGLMap (MapWidget)

Interactive map widget using KeplerGL.

KeplerGL is a powerful data visualization tool built on top of deck.gl. This class provides a Python interface for adding data and configuring the KeplerGL visualization.

Note: KeplerGL is loaded from CDN due to its React-based architecture.

Examples:

>>> from anymap_ts import KeplerGLMap
>>> import pandas as pd
>>> m = KeplerGLMap()
>>> df = pd.DataFrame({
...     'lat': [37.7749, 37.8044],
...     'lng': [-122.4194, -122.2712],
...     'value': [100, 200]
... })
>>> m.add_data(df, name='points')
>>> m
Source code in anymap_ts/keplergl.py
class KeplerGLMap(MapWidget):
    """Interactive map widget using KeplerGL.

    KeplerGL is a powerful data visualization tool built on top of deck.gl.
    This class provides a Python interface for adding data and configuring
    the KeplerGL visualization.

    Note: KeplerGL is loaded from CDN due to its React-based architecture.

    Example:
        >>> from anymap_ts import KeplerGLMap
        >>> import pandas as pd
        >>> m = KeplerGLMap()
        >>> df = pd.DataFrame({
        ...     'lat': [37.7749, 37.8044],
        ...     'lng': [-122.4194, -122.2712],
        ...     'value': [100, 200]
        ... })
        >>> m.add_data(df, name='points')
        >>> m
    """

    # ESM module for frontend
    _esm = STATIC_DIR / "keplergl.js"

    # KeplerGL-specific traits
    config = traitlets.Dict({}).tag(sync=True)
    datasets = traitlets.Dict({}).tag(sync=True)
    read_only = traitlets.Bool(False).tag(sync=True)
    show_data_table = traitlets.Bool(True).tag(sync=True)

    # Mapbox token for basemaps
    mapbox_token = traitlets.Unicode("").tag(sync=True)

    def __init__(
        self,
        center: Tuple[float, float] = (-122.4, 37.8),
        zoom: float = 10.0,
        width: str = "100%",
        height: str = "600px",
        config: Optional[Dict] = None,
        read_only: bool = False,
        show_data_table: bool = True,
        mapbox_token: Optional[str] = None,
        **kwargs,
    ):
        """Initialize a KeplerGL map.

        Args:
            center: Map center as (longitude, latitude).
            zoom: Initial zoom level.
            width: Widget width as CSS string.
            height: Widget height as CSS string.
            config: KeplerGL configuration dict.
            read_only: Whether the UI is read-only.
            show_data_table: Whether to show the data table panel.
            mapbox_token: Mapbox access token for basemaps.
            **kwargs: Additional widget arguments.
        """
        import os

        if mapbox_token is None:
            mapbox_token = os.environ.get("MAPBOX_TOKEN", "")

        super().__init__(
            center=list(center),
            zoom=zoom,
            width=width,
            height=height,
            config=config or {},
            read_only=read_only,
            show_data_table=show_data_table,
            mapbox_token=mapbox_token,
            **kwargs,
        )
        self.datasets = {}

    # -------------------------------------------------------------------------
    # Data Methods
    # -------------------------------------------------------------------------

    def add_data(
        self,
        data: Any,
        name: Optional[str] = None,
    ) -> None:
        """Add data to the map.

        Args:
            data: Data to add (DataFrame, GeoDataFrame, dict, or file path).
            name: Dataset name/label.
        """
        dataset_id = name or f"data_{uuid.uuid4().hex[:8]}"
        processed_data = self._process_data(data)

        self.datasets = {
            **self.datasets,
            dataset_id: {
                "info": {
                    "id": dataset_id,
                    "label": dataset_id,
                },
                "data": processed_data,
            },
        }

        self.call_js_method(
            "addData",
            dataId=dataset_id,
            data=processed_data,
        )

    def _process_data(self, data: Any) -> Dict:
        """Process data into KeplerGL format.

        Args:
            data: Input data.

        Returns:
            Processed data dict with fields and rows.
        """
        # Handle DataFrame
        if hasattr(data, "to_dict"):
            # Check if it's a GeoDataFrame
            if hasattr(data, "geometry"):
                # Convert to GeoJSON for geometry columns
                geojson = json.loads(data.to_json())
                return {
                    "type": "geojson",
                    "data": geojson,
                }
            else:
                # Regular DataFrame
                fields = []
                for col in data.columns:
                    dtype = str(data[col].dtype)
                    if "int" in dtype:
                        field_type = "integer"
                    elif "float" in dtype:
                        field_type = "real"
                    elif "datetime" in dtype:
                        field_type = "timestamp"
                    elif "bool" in dtype:
                        field_type = "boolean"
                    else:
                        field_type = "string"

                    fields.append({"name": col, "type": field_type})

                # Convert to list of lists
                rows = data.values.tolist()

                return {
                    "fields": fields,
                    "rows": rows,
                }

        # Handle dict (assume it's already GeoJSON or processed)
        if isinstance(data, dict):
            if "type" in data and data["type"] in [
                "FeatureCollection",
                "Feature",
                "Point",
                "LineString",
                "Polygon",
                "MultiPoint",
                "MultiLineString",
                "MultiPolygon",
            ]:
                return {"type": "geojson", "data": data}
            return data

        # Handle file path
        if isinstance(data, (str, Path)):
            path = Path(data)
            if path.exists():
                if path.suffix.lower() in [".geojson", ".json"]:
                    with open(path) as f:
                        geojson = json.load(f)
                    return {"type": "geojson", "data": geojson}
                elif path.suffix.lower() == ".csv":
                    try:
                        import pandas as pd

                        df = pd.read_csv(path)
                        return self._process_data(df)
                    except ImportError:
                        raise ImportError(
                            "pandas is required to load CSV files. "
                            "Install with: pip install pandas"
                        )

        return data

    def remove_data(self, name: str) -> None:
        """Remove a dataset.

        Args:
            name: Dataset name to remove.
        """
        if name in self.datasets:
            datasets = dict(self.datasets)
            del datasets[name]
            self.datasets = datasets
        self.call_js_method("removeData", dataId=name)

    # -------------------------------------------------------------------------
    # Configuration Methods
    # -------------------------------------------------------------------------

    def set_config(self, config: Dict) -> None:
        """Set the KeplerGL configuration.

        Args:
            config: Configuration dict.
        """
        self.config = config
        self.call_js_method("setConfig", config=config)

    def get_config(self) -> Dict:
        """Get the current KeplerGL configuration.

        Returns:
            Configuration dict.
        """
        return self.config

    def save_config(self, filepath: Union[str, Path]) -> None:
        """Save configuration to a JSON file.

        Args:
            filepath: Path to save the configuration.
        """
        with open(filepath, "w") as f:
            json.dump(self.config, f, indent=2)

    def load_config(self, filepath: Union[str, Path]) -> None:
        """Load configuration from a JSON file.

        Args:
            filepath: Path to the configuration file.
        """
        with open(filepath) as f:
            config = json.load(f)
        self.set_config(config)

    # -------------------------------------------------------------------------
    # Filter Methods
    # -------------------------------------------------------------------------

    def add_filter(
        self,
        data_id: str,
        field: str,
        filter_type: str = "range",
        value: Optional[Any] = None,
    ) -> None:
        """Add a filter to the visualization.

        Args:
            data_id: Dataset ID to filter.
            field: Field name to filter on.
            filter_type: Type of filter ('range', 'select', 'time').
            value: Filter value(s).
        """
        filter_config = {
            "dataId": [data_id],
            "name": [field],
            "type": filter_type,
        }
        if value is not None:
            filter_config["value"] = value

        self.call_js_method("addFilter", filter=filter_config)

    # -------------------------------------------------------------------------
    # Layer Methods
    # -------------------------------------------------------------------------

    def add_layer(
        self,
        layer_type: str,
        data_id: str,
        columns: Dict[str, str],
        label: Optional[str] = None,
        color: Optional[List[int]] = None,
        vis_config: Optional[Dict] = None,
        **kwargs,
    ) -> None:
        """Add a layer to the visualization.

        Args:
            layer_type: Layer type ('point', 'arc', 'line', 'hexagon', 'heatmap', etc.).
            data_id: Dataset ID for the layer.
            columns: Column mapping (e.g., {'lat': 'latitude', 'lng': 'longitude'}).
            label: Layer label.
            color: Layer color as [r, g, b].
            vis_config: Visual configuration.
            **kwargs: Additional layer options.
        """
        layer_config = {
            "type": layer_type,
            "config": {
                "dataId": data_id,
                "label": label or f"{layer_type}_layer",
                "columns": columns,
                "isVisible": True,
            },
        }
        if color:
            layer_config["config"]["color"] = color
        if vis_config:
            layer_config["config"]["visConfig"] = vis_config

        layer_config["config"].update(kwargs)

        self.call_js_method("addLayer", layer=layer_config)

    # -------------------------------------------------------------------------
    # View Methods
    # -------------------------------------------------------------------------

    def fly_to(
        self,
        lng: float,
        lat: float,
        zoom: Optional[float] = None,
    ) -> None:
        """Fly to a location.

        Args:
            lng: Target longitude.
            lat: Target latitude.
            zoom: Target zoom level.
        """
        self.center = [lng, lat]
        if zoom is not None:
            self.zoom = zoom
        self.call_js_method("flyTo", lng=lng, lat=lat, zoom=zoom or self.zoom)

    # -------------------------------------------------------------------------
    # HTML Export
    # -------------------------------------------------------------------------

    def _generate_html_template(self) -> str:
        """Generate standalone HTML for KeplerGL."""
        template_path = Path(__file__).parent / "templates" / "keplergl.html"

        if template_path.exists():
            template = template_path.read_text(encoding="utf-8")
        else:
            template = self._get_default_template()

        state = {
            "center": self.center,
            "zoom": self.zoom,
            "config": self.config,
            "datasets": self.datasets,
            "read_only": self.read_only,
            "mapbox_token": self.mapbox_token,
            "width": self.width,
            "height": self.height,
            "js_calls": self._js_calls,
        }

        template = template.replace("{{state}}", json.dumps(state, indent=2))
        return template

    def _get_default_template(self) -> str:
        """Get default HTML template."""
        return """<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>KeplerGL Map</title>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <style>
        * { margin: 0; padding: 0; box-sizing: border-box; }
        html, body { height: 100%; }
        #app { position: absolute; top: 0; bottom: 0; width: 100%; }
    </style>
</head>
<body>
    <div id="app"></div>
    <script>
        const state = {{state}};
        // KeplerGL requires React/Redux setup - simplified placeholder
        document.getElementById('app').innerHTML = '<p>KeplerGL visualization requires full React setup. Use Jupyter widget for interactive visualization.</p>';
    </script>
</body>
</html>"""

    def _repr_html_(self) -> str:
        """Return HTML representation for Jupyter (uses iframe with CDN KeplerGL)."""
        state = {
            "center": self.center,
            "zoom": self.zoom,
            "config": self.config,
            "datasets": self.datasets,
            "mapbox_token": self.mapbox_token,
        }

        html = f"""
        <iframe
            srcdoc='
            <!DOCTYPE html>
            <html>
            <head>
                <meta charset="utf-8">
                <script src="https://unpkg.com/react@16.8.4/umd/react.production.min.js"></script>
                <script src="https://unpkg.com/react-dom@16.8.4/umd/react-dom.production.min.js"></script>
                <script src="https://unpkg.com/kepler.gl@3.0.0/umd/keplergl.min.js"></script>
                <link href="https://unpkg.com/kepler.gl@3.0.0/umd/keplergl.min.css" rel="stylesheet" />
                <style>
                    body {{ margin: 0; padding: 0; overflow: hidden; }}
                    #app {{ width: 100vw; height: 100vh; }}
                </style>
            </head>
            <body>
                <div id="app"></div>
                <script>
                    const state = {json.dumps(state)};
                    // KeplerGL requires complex React setup
                    document.getElementById("app").innerHTML = "KeplerGL widget - use anywidget interface for full interactivity";
                </script>
            </body>
            </html>
            '
            width="{self.width}"
            height="{self.height}"
            frameborder="0"
        ></iframe>
        """
        return html

__init__(self, center=(-122.4, 37.8), zoom=10.0, width='100%', height='600px', config=None, read_only=False, show_data_table=True, mapbox_token=None, **kwargs) special

Initialize a KeplerGL map.

Parameters:

Name Type Description Default
center Tuple[float, float]

Map center as (longitude, latitude).

(-122.4, 37.8)
zoom float

Initial zoom level.

10.0
width str

Widget width as CSS string.

'100%'
height str

Widget height as CSS string.

'600px'
config Optional[Dict]

KeplerGL configuration dict.

None
read_only bool

Whether the UI is read-only.

False
show_data_table bool

Whether to show the data table panel.

True
mapbox_token Optional[str]

Mapbox access token for basemaps.

None
**kwargs

Additional widget arguments.

{}
Source code in anymap_ts/keplergl.py
def __init__(
    self,
    center: Tuple[float, float] = (-122.4, 37.8),
    zoom: float = 10.0,
    width: str = "100%",
    height: str = "600px",
    config: Optional[Dict] = None,
    read_only: bool = False,
    show_data_table: bool = True,
    mapbox_token: Optional[str] = None,
    **kwargs,
):
    """Initialize a KeplerGL map.

    Args:
        center: Map center as (longitude, latitude).
        zoom: Initial zoom level.
        width: Widget width as CSS string.
        height: Widget height as CSS string.
        config: KeplerGL configuration dict.
        read_only: Whether the UI is read-only.
        show_data_table: Whether to show the data table panel.
        mapbox_token: Mapbox access token for basemaps.
        **kwargs: Additional widget arguments.
    """
    import os

    if mapbox_token is None:
        mapbox_token = os.environ.get("MAPBOX_TOKEN", "")

    super().__init__(
        center=list(center),
        zoom=zoom,
        width=width,
        height=height,
        config=config or {},
        read_only=read_only,
        show_data_table=show_data_table,
        mapbox_token=mapbox_token,
        **kwargs,
    )
    self.datasets = {}

add_data(self, data, name=None)

Add data to the map.

Parameters:

Name Type Description Default
data Any

Data to add (DataFrame, GeoDataFrame, dict, or file path).

required
name Optional[str]

Dataset name/label.

None
Source code in anymap_ts/keplergl.py
def add_data(
    self,
    data: Any,
    name: Optional[str] = None,
) -> None:
    """Add data to the map.

    Args:
        data: Data to add (DataFrame, GeoDataFrame, dict, or file path).
        name: Dataset name/label.
    """
    dataset_id = name or f"data_{uuid.uuid4().hex[:8]}"
    processed_data = self._process_data(data)

    self.datasets = {
        **self.datasets,
        dataset_id: {
            "info": {
                "id": dataset_id,
                "label": dataset_id,
            },
            "data": processed_data,
        },
    }

    self.call_js_method(
        "addData",
        dataId=dataset_id,
        data=processed_data,
    )

add_filter(self, data_id, field, filter_type='range', value=None)

Add a filter to the visualization.

Parameters:

Name Type Description Default
data_id str

Dataset ID to filter.

required
field str

Field name to filter on.

required
filter_type str

Type of filter ('range', 'select', 'time').

'range'
value Optional[Any]

Filter value(s).

None
Source code in anymap_ts/keplergl.py
def add_filter(
    self,
    data_id: str,
    field: str,
    filter_type: str = "range",
    value: Optional[Any] = None,
) -> None:
    """Add a filter to the visualization.

    Args:
        data_id: Dataset ID to filter.
        field: Field name to filter on.
        filter_type: Type of filter ('range', 'select', 'time').
        value: Filter value(s).
    """
    filter_config = {
        "dataId": [data_id],
        "name": [field],
        "type": filter_type,
    }
    if value is not None:
        filter_config["value"] = value

    self.call_js_method("addFilter", filter=filter_config)

add_layer(self, layer_type, data_id, columns, label=None, color=None, vis_config=None, **kwargs)

Add a layer to the visualization.

Parameters:

Name Type Description Default
layer_type str

Layer type ('point', 'arc', 'line', 'hexagon', 'heatmap', etc.).

required
data_id str

Dataset ID for the layer.

required
columns Dict[str, str]

Column mapping (e.g., {'lat': 'latitude', 'lng': 'longitude'}).

required
label Optional[str]

Layer label.

None
color Optional[List[int]]

Layer color as [r, g, b].

None
vis_config Optional[Dict]

Visual configuration.

None
**kwargs

Additional layer options.

{}
Source code in anymap_ts/keplergl.py
def add_layer(
    self,
    layer_type: str,
    data_id: str,
    columns: Dict[str, str],
    label: Optional[str] = None,
    color: Optional[List[int]] = None,
    vis_config: Optional[Dict] = None,
    **kwargs,
) -> None:
    """Add a layer to the visualization.

    Args:
        layer_type: Layer type ('point', 'arc', 'line', 'hexagon', 'heatmap', etc.).
        data_id: Dataset ID for the layer.
        columns: Column mapping (e.g., {'lat': 'latitude', 'lng': 'longitude'}).
        label: Layer label.
        color: Layer color as [r, g, b].
        vis_config: Visual configuration.
        **kwargs: Additional layer options.
    """
    layer_config = {
        "type": layer_type,
        "config": {
            "dataId": data_id,
            "label": label or f"{layer_type}_layer",
            "columns": columns,
            "isVisible": True,
        },
    }
    if color:
        layer_config["config"]["color"] = color
    if vis_config:
        layer_config["config"]["visConfig"] = vis_config

    layer_config["config"].update(kwargs)

    self.call_js_method("addLayer", layer=layer_config)

fly_to(self, lng, lat, zoom=None)

Fly to a location.

Parameters:

Name Type Description Default
lng float

Target longitude.

required
lat float

Target latitude.

required
zoom Optional[float]

Target zoom level.

None
Source code in anymap_ts/keplergl.py
def fly_to(
    self,
    lng: float,
    lat: float,
    zoom: Optional[float] = None,
) -> None:
    """Fly to a location.

    Args:
        lng: Target longitude.
        lat: Target latitude.
        zoom: Target zoom level.
    """
    self.center = [lng, lat]
    if zoom is not None:
        self.zoom = zoom
    self.call_js_method("flyTo", lng=lng, lat=lat, zoom=zoom or self.zoom)

get_config(self)

Get the current KeplerGL configuration.

Returns:

Type Description
Dict

Configuration dict.

Source code in anymap_ts/keplergl.py
def get_config(self) -> Dict:
    """Get the current KeplerGL configuration.

    Returns:
        Configuration dict.
    """
    return self.config

load_config(self, filepath)

Load configuration from a JSON file.

Parameters:

Name Type Description Default
filepath Union[str, Path]

Path to the configuration file.

required
Source code in anymap_ts/keplergl.py
def load_config(self, filepath: Union[str, Path]) -> None:
    """Load configuration from a JSON file.

    Args:
        filepath: Path to the configuration file.
    """
    with open(filepath) as f:
        config = json.load(f)
    self.set_config(config)

remove_data(self, name)

Remove a dataset.

Parameters:

Name Type Description Default
name str

Dataset name to remove.

required
Source code in anymap_ts/keplergl.py
def remove_data(self, name: str) -> None:
    """Remove a dataset.

    Args:
        name: Dataset name to remove.
    """
    if name in self.datasets:
        datasets = dict(self.datasets)
        del datasets[name]
        self.datasets = datasets
    self.call_js_method("removeData", dataId=name)

save_config(self, filepath)

Save configuration to a JSON file.

Parameters:

Name Type Description Default
filepath Union[str, Path]

Path to save the configuration.

required
Source code in anymap_ts/keplergl.py
def save_config(self, filepath: Union[str, Path]) -> None:
    """Save configuration to a JSON file.

    Args:
        filepath: Path to save the configuration.
    """
    with open(filepath, "w") as f:
        json.dump(self.config, f, indent=2)

set_config(self, config)

Set the KeplerGL configuration.

Parameters:

Name Type Description Default
config Dict

Configuration dict.

required
Source code in anymap_ts/keplergl.py
def set_config(self, config: Dict) -> None:
    """Set the KeplerGL configuration.

    Args:
        config: Configuration dict.
    """
    self.config = config
    self.call_js_method("setConfig", config=config)

leaflet

Leaflet map widget implementation.

LeafletMap (MapWidget)

Interactive map widget using Leaflet.

This class provides a Python interface to Leaflet maps with full bidirectional communication through anywidget.

Note

Leaflet uses [lat, lng] order internally, but this class accepts [lng, lat] for consistency with other map libraries.

Examples:

>>> from anymap_ts import LeafletMap
>>> m = LeafletMap(center=[-122.4, 37.8], zoom=10)
>>> m.add_basemap("OpenStreetMap")
>>> m
Source code in anymap_ts/leaflet.py
class LeafletMap(MapWidget):
    """Interactive map widget using Leaflet.

    This class provides a Python interface to Leaflet maps with
    full bidirectional communication through anywidget.

    Note:
        Leaflet uses [lat, lng] order internally, but this class
        accepts [lng, lat] for consistency with other map libraries.

    Example:
        >>> from anymap_ts import LeafletMap
        >>> m = LeafletMap(center=[-122.4, 37.8], zoom=10)
        >>> m.add_basemap("OpenStreetMap")
        >>> m
    """

    # ESM module for frontend
    _esm = STATIC_DIR / "leaflet.js"
    _css = STATIC_DIR / "leaflet.css"

    # Layer tracking
    _layer_dict = traitlets.Dict({}).tag(sync=True)

    def __init__(
        self,
        center: Tuple[float, float] = (0.0, 0.0),
        zoom: float = 2.0,
        width: str = "100%",
        height: str = "600px",
        controls: Optional[Dict[str, Any]] = None,
        **kwargs,
    ):
        """Initialize a Leaflet map.

        Args:
            center: Map center as (longitude, latitude).
            zoom: Initial zoom level.
            width: Map width as CSS string.
            height: Map height as CSS string.
            controls: Dict of controls to add (e.g., {"zoom": True}).
            **kwargs: Additional widget arguments.
        """
        super().__init__(
            center=list(center),
            zoom=zoom,
            width=width,
            height=height,
            style="",  # Leaflet doesn't use style URLs
            **kwargs,
        )

        # Initialize layer dictionary
        self._layer_dict = {"Background": []}

        # Add default controls
        if controls is None:
            controls = {
                "scale": {"position": "bottom-left"},
                "attribution": {"position": "bottom-right"},
                "layers": {"position": "top-right"},
            }

        for control_name, config in controls.items():
            if config:
                self.add_control(
                    control_name, **(config if isinstance(config, dict) else {})
                )

    # -------------------------------------------------------------------------
    # Basemap Methods
    # -------------------------------------------------------------------------

    def add_basemap(
        self,
        basemap: str = "OpenStreetMap",
        attribution: Optional[str] = None,
        **kwargs,
    ) -> None:
        """Add a basemap layer.

        Args:
            basemap: Name of basemap provider (e.g., "OpenStreetMap", "CartoDB.Positron").
            attribution: Custom attribution text.
            **kwargs: Additional options.
        """
        try:
            url, default_attribution = get_basemap_url(basemap)
        except (ValueError, KeyError):
            url = basemap
            default_attribution = ""

        self.call_js_method(
            "addBasemap",
            url,
            attribution=attribution or default_attribution,
            name=basemap,
            **kwargs,
        )

        # Track in layer dict
        basemaps = self._layer_dict.get("Basemaps", [])
        if basemap not in basemaps:
            self._layer_dict = {
                **self._layer_dict,
                "Basemaps": basemaps + [basemap],
            }

    # -------------------------------------------------------------------------
    # Vector Data Methods
    # -------------------------------------------------------------------------

    def add_vector(
        self,
        data: Any,
        style: Optional[Dict] = None,
        name: Optional[str] = None,
        fit_bounds: bool = True,
        **kwargs,
    ) -> None:
        """Add vector data to the map.

        Supports GeoJSON, GeoDataFrame, or file paths to vector formats.

        Args:
            data: GeoJSON dict, GeoDataFrame, or path to vector file.
            style: Leaflet style properties.
            name: Layer name.
            fit_bounds: Whether to fit map to data bounds.
            **kwargs: Additional layer options.
        """
        geojson = to_geojson(data)

        # Handle URL data
        if geojson.get("type") == "url":
            self.add_geojson(
                geojson["url"],
                style=style,
                name=name,
                fit_bounds=fit_bounds,
                **kwargs,
            )
            return

        layer_id = name or f"vector-{len(self._layers)}"

        # Get default style if not provided
        if style is None:
            layer_type = _infer_leaflet_type(geojson)
            style = _get_default_style(layer_type)

        # Get bounds
        bounds = get_bounds(data) if fit_bounds else None

        # Call JavaScript
        self.call_js_method(
            "addGeoJSON",
            data=geojson,
            name=layer_id,
            style=style,
            fitBounds=fit_bounds,
            bounds=bounds,
            **kwargs,
        )

        # Track layer
        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "geojson",
                "style": style,
            },
        }

    def add_geojson(
        self,
        data: Union[str, Dict],
        style: Optional[Dict] = None,
        name: Optional[str] = None,
        fit_bounds: bool = True,
        **kwargs,
    ) -> None:
        """Add GeoJSON data to the map.

        Args:
            data: GeoJSON dict or URL to GeoJSON file.
            style: Leaflet style properties.
            name: Layer name.
            fit_bounds: Whether to fit map to data bounds.
            **kwargs: Additional layer options.
        """
        self.add_vector(
            data,
            style=style,
            name=name,
            fit_bounds=fit_bounds,
            **kwargs,
        )

    # -------------------------------------------------------------------------
    # Raster Data Methods
    # -------------------------------------------------------------------------

    def add_tile_layer(
        self,
        url: str,
        name: Optional[str] = None,
        attribution: str = "",
        min_zoom: int = 0,
        max_zoom: int = 22,
        opacity: float = 1.0,
        **kwargs,
    ) -> None:
        """Add an XYZ tile layer.

        Args:
            url: Tile URL template with {x}, {y}, {z} placeholders.
            name: Layer name.
            attribution: Attribution text.
            min_zoom: Minimum zoom level.
            max_zoom: Maximum zoom level.
            opacity: Layer opacity.
            **kwargs: Additional options.
        """
        layer_id = name or f"tiles-{len(self._layers)}"

        self.call_js_method(
            "addTileLayer",
            url,
            name=layer_id,
            attribution=attribution,
            minZoom=min_zoom,
            maxZoom=max_zoom,
            opacity=opacity,
            **kwargs,
        )

        # Track layer
        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "tile",
            },
        }

    # -------------------------------------------------------------------------
    # Layer Management
    # -------------------------------------------------------------------------

    def remove_layer(self, layer_id: str) -> None:
        """Remove a layer from the map.

        Args:
            layer_id: Layer identifier to remove.
        """
        if layer_id in self._layers:
            layers = dict(self._layers)
            del layers[layer_id]
            self._layers = layers
        self.call_js_method("removeLayer", layer_id)

    def set_visibility(self, layer_id: str, visible: bool) -> None:
        """Set layer visibility.

        Args:
            layer_id: Layer identifier.
            visible: Whether layer should be visible.
        """
        self.call_js_method("setVisibility", layer_id, visible)

    def set_opacity(self, layer_id: str, opacity: float) -> None:
        """Set layer opacity.

        Args:
            layer_id: Layer identifier.
            opacity: Opacity value between 0 and 1.
        """
        self.call_js_method("setOpacity", layer_id, opacity)

    # -------------------------------------------------------------------------
    # Controls
    # -------------------------------------------------------------------------

    def add_control(
        self,
        control_type: str,
        position: str = "topright",
        **kwargs,
    ) -> None:
        """Add a map control.

        Args:
            control_type: Type of control ('zoom', 'scale', 'attribution', 'layers').
            position: Control position ('topleft', 'topright', 'bottomleft', 'bottomright').
            **kwargs: Control-specific options.
        """
        # Convert position format
        position_map = {
            "top-left": "topleft",
            "top-right": "topright",
            "bottom-left": "bottomleft",
            "bottom-right": "bottomright",
        }
        pos = position_map.get(position, position)

        self.call_js_method("addControl", control_type, position=pos, **kwargs)
        self._controls = {
            **self._controls,
            control_type: {"type": control_type, "position": pos, **kwargs},
        }

    def remove_control(self, control_type: str) -> None:
        """Remove a map control.

        Args:
            control_type: Type of control to remove.
        """
        self.call_js_method("removeControl", control_type)
        if control_type in self._controls:
            controls = dict(self._controls)
            del controls[control_type]
            self._controls = controls

    def add_layer_control(
        self,
        position: str = "topright",
        collapsed: bool = True,
    ) -> None:
        """Add a layer control for toggling layer visibility.

        Args:
            position: Control position.
            collapsed: Whether control starts collapsed.
        """
        self.add_control("layers", position=position, collapsed=collapsed)

    # -------------------------------------------------------------------------
    # Markers
    # -------------------------------------------------------------------------

    def add_marker(
        self,
        lng: float,
        lat: float,
        popup: Optional[str] = None,
        marker_id: Optional[str] = None,
    ) -> None:
        """Add a marker to the map.

        Args:
            lng: Longitude.
            lat: Latitude.
            popup: HTML content for popup.
            marker_id: Unique marker ID.
        """
        self.call_js_method("addMarker", lng, lat, popup=popup, id=marker_id)

    def remove_marker(self, marker_id: str) -> None:
        """Remove a marker from the map.

        Args:
            marker_id: Marker ID to remove.
        """
        self.call_js_method("removeMarker", marker_id)

    # -------------------------------------------------------------------------
    # HTML Export
    # -------------------------------------------------------------------------

    def _generate_html_template(self) -> str:
        """Generate standalone HTML for the map."""
        template_path = Path(__file__).parent / "templates" / "leaflet.html"

        if template_path.exists():
            template = template_path.read_text(encoding="utf-8")
        else:
            template = self._get_default_template()

        # Serialize state
        state = {
            "center": self.center,
            "zoom": self.zoom,
            "width": self.width,
            "height": self.height,
            "layers": self._layers,
            "controls": self._controls,
            "js_calls": self._js_calls,
        }

        template = template.replace("{{state}}", json.dumps(state, indent=2))
        return template

    def _get_default_template(self) -> str:
        """Get default HTML template."""
        return """<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>{{title}}</title>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css" />
    <script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>
    <style>
        body { margin: 0; padding: 0; }
        #map { position: absolute; top: 0; bottom: 0; width: 100%; }
    </style>
</head>
<body>
    <div id="map"></div>
    <script>
        const state = {{state}};

        // Note: Leaflet uses [lat, lng], but we store [lng, lat]
        const map = L.map('map').setView([state.center[1], state.center[0]], state.zoom);

        // Replay JS calls
        for (const call of state.js_calls || []) {
            try {
                executeMethod(call.method, call.args, call.kwargs);
            } catch (e) {
                console.error('Error executing', call.method, e);
            }
        }

        function executeMethod(method, args, kwargs) {
            switch (method) {
                case 'addBasemap':
                case 'addTileLayer':
                    const url = args[0];
                    L.tileLayer(url, {
                        attribution: kwargs.attribution || '',
                        maxZoom: kwargs.maxZoom || 22,
                        minZoom: kwargs.minZoom || 0,
                        opacity: kwargs.opacity || 1
                    }).addTo(map);
                    break;

                case 'addGeoJSON':
                    const geojson = kwargs.data;
                    const style = kwargs.style || {
                        color: '#3388ff',
                        weight: 2,
                        opacity: 0.8,
                        fillOpacity: 0.5
                    };
                    const layer = L.geoJSON(geojson, {
                        style: style,
                        pointToLayer: (feature, latlng) => L.circleMarker(latlng, style)
                    }).addTo(map);

                    if (kwargs.fitBounds) {
                        map.fitBounds(layer.getBounds(), { padding: [50, 50] });
                    }
                    break;

                case 'addControl':
                    const controlType = args[0];
                    const position = kwargs.position || 'topright';
                    if (controlType === 'zoom' || controlType === 'navigation') {
                        L.control.zoom({ position }).addTo(map);
                    } else if (controlType === 'scale') {
                        L.control.scale({ position, imperial: false }).addTo(map);
                    }
                    break;

                case 'addMarker':
                    const [lng, lat] = args;
                    const marker = L.marker([lat, lng]).addTo(map);
                    if (kwargs.popup) {
                        marker.bindPopup(kwargs.popup);
                    }
                    break;

                case 'flyTo':
                    map.flyTo([args[1], args[0]], kwargs.zoom || map.getZoom(), {
                        duration: (kwargs.duration || 2000) / 1000
                    });
                    break;

                case 'fitBounds':
                    const bounds = args[0];
                    map.fitBounds([
                        [bounds[1], bounds[0]],
                        [bounds[3], bounds[2]]
                    ], { padding: [kwargs.padding || 50, kwargs.padding || 50] });
                    break;

                default:
                    console.log('Unknown method:', method);
            }
        }
    </script>
</body>
</html>"""

__init__(self, center=(0.0, 0.0), zoom=2.0, width='100%', height='600px', controls=None, **kwargs) special

Initialize a Leaflet map.

Parameters:

Name Type Description Default
center Tuple[float, float]

Map center as (longitude, latitude).

(0.0, 0.0)
zoom float

Initial zoom level.

2.0
width str

Map width as CSS string.

'100%'
height str

Map height as CSS string.

'600px'
controls Optional[Dict[str, Any]]

Dict of controls to add (e.g., {"zoom": True}).

None
**kwargs

Additional widget arguments.

{}
Source code in anymap_ts/leaflet.py
def __init__(
    self,
    center: Tuple[float, float] = (0.0, 0.0),
    zoom: float = 2.0,
    width: str = "100%",
    height: str = "600px",
    controls: Optional[Dict[str, Any]] = None,
    **kwargs,
):
    """Initialize a Leaflet map.

    Args:
        center: Map center as (longitude, latitude).
        zoom: Initial zoom level.
        width: Map width as CSS string.
        height: Map height as CSS string.
        controls: Dict of controls to add (e.g., {"zoom": True}).
        **kwargs: Additional widget arguments.
    """
    super().__init__(
        center=list(center),
        zoom=zoom,
        width=width,
        height=height,
        style="",  # Leaflet doesn't use style URLs
        **kwargs,
    )

    # Initialize layer dictionary
    self._layer_dict = {"Background": []}

    # Add default controls
    if controls is None:
        controls = {
            "scale": {"position": "bottom-left"},
            "attribution": {"position": "bottom-right"},
            "layers": {"position": "top-right"},
        }

    for control_name, config in controls.items():
        if config:
            self.add_control(
                control_name, **(config if isinstance(config, dict) else {})
            )

add_basemap(self, basemap='OpenStreetMap', attribution=None, **kwargs)

Add a basemap layer.

Parameters:

Name Type Description Default
basemap str

Name of basemap provider (e.g., "OpenStreetMap", "CartoDB.Positron").

'OpenStreetMap'
attribution Optional[str]

Custom attribution text.

None
**kwargs

Additional options.

{}
Source code in anymap_ts/leaflet.py
def add_basemap(
    self,
    basemap: str = "OpenStreetMap",
    attribution: Optional[str] = None,
    **kwargs,
) -> None:
    """Add a basemap layer.

    Args:
        basemap: Name of basemap provider (e.g., "OpenStreetMap", "CartoDB.Positron").
        attribution: Custom attribution text.
        **kwargs: Additional options.
    """
    try:
        url, default_attribution = get_basemap_url(basemap)
    except (ValueError, KeyError):
        url = basemap
        default_attribution = ""

    self.call_js_method(
        "addBasemap",
        url,
        attribution=attribution or default_attribution,
        name=basemap,
        **kwargs,
    )

    # Track in layer dict
    basemaps = self._layer_dict.get("Basemaps", [])
    if basemap not in basemaps:
        self._layer_dict = {
            **self._layer_dict,
            "Basemaps": basemaps + [basemap],
        }

add_control(self, control_type, position='topright', **kwargs)

Add a map control.

Parameters:

Name Type Description Default
control_type str

Type of control ('zoom', 'scale', 'attribution', 'layers').

required
position str

Control position ('topleft', 'topright', 'bottomleft', 'bottomright').

'topright'
**kwargs

Control-specific options.

{}
Source code in anymap_ts/leaflet.py
def add_control(
    self,
    control_type: str,
    position: str = "topright",
    **kwargs,
) -> None:
    """Add a map control.

    Args:
        control_type: Type of control ('zoom', 'scale', 'attribution', 'layers').
        position: Control position ('topleft', 'topright', 'bottomleft', 'bottomright').
        **kwargs: Control-specific options.
    """
    # Convert position format
    position_map = {
        "top-left": "topleft",
        "top-right": "topright",
        "bottom-left": "bottomleft",
        "bottom-right": "bottomright",
    }
    pos = position_map.get(position, position)

    self.call_js_method("addControl", control_type, position=pos, **kwargs)
    self._controls = {
        **self._controls,
        control_type: {"type": control_type, "position": pos, **kwargs},
    }

add_geojson(self, data, style=None, name=None, fit_bounds=True, **kwargs)

Add GeoJSON data to the map.

Parameters:

Name Type Description Default
data Union[str, Dict]

GeoJSON dict or URL to GeoJSON file.

required
style Optional[Dict]

Leaflet style properties.

None
name Optional[str]

Layer name.

None
fit_bounds bool

Whether to fit map to data bounds.

True
**kwargs

Additional layer options.

{}
Source code in anymap_ts/leaflet.py
def add_geojson(
    self,
    data: Union[str, Dict],
    style: Optional[Dict] = None,
    name: Optional[str] = None,
    fit_bounds: bool = True,
    **kwargs,
) -> None:
    """Add GeoJSON data to the map.

    Args:
        data: GeoJSON dict or URL to GeoJSON file.
        style: Leaflet style properties.
        name: Layer name.
        fit_bounds: Whether to fit map to data bounds.
        **kwargs: Additional layer options.
    """
    self.add_vector(
        data,
        style=style,
        name=name,
        fit_bounds=fit_bounds,
        **kwargs,
    )

add_layer_control(self, position='topright', collapsed=True)

Add a layer control for toggling layer visibility.

Parameters:

Name Type Description Default
position str

Control position.

'topright'
collapsed bool

Whether control starts collapsed.

True
Source code in anymap_ts/leaflet.py
def add_layer_control(
    self,
    position: str = "topright",
    collapsed: bool = True,
) -> None:
    """Add a layer control for toggling layer visibility.

    Args:
        position: Control position.
        collapsed: Whether control starts collapsed.
    """
    self.add_control("layers", position=position, collapsed=collapsed)

add_marker(self, lng, lat, popup=None, marker_id=None)

Add a marker to the map.

Parameters:

Name Type Description Default
lng float

Longitude.

required
lat float

Latitude.

required
popup Optional[str]

HTML content for popup.

None
marker_id Optional[str]

Unique marker ID.

None
Source code in anymap_ts/leaflet.py
def add_marker(
    self,
    lng: float,
    lat: float,
    popup: Optional[str] = None,
    marker_id: Optional[str] = None,
) -> None:
    """Add a marker to the map.

    Args:
        lng: Longitude.
        lat: Latitude.
        popup: HTML content for popup.
        marker_id: Unique marker ID.
    """
    self.call_js_method("addMarker", lng, lat, popup=popup, id=marker_id)

add_tile_layer(self, url, name=None, attribution='', min_zoom=0, max_zoom=22, opacity=1.0, **kwargs)

Add an XYZ tile layer.

Parameters:

Name Type Description Default
url str

Tile URL template with {x}, {y}, {z} placeholders.

required
name Optional[str]

Layer name.

None
attribution str

Attribution text.

''
min_zoom int

Minimum zoom level.

0
max_zoom int

Maximum zoom level.

22
opacity float

Layer opacity.

1.0
**kwargs

Additional options.

{}
Source code in anymap_ts/leaflet.py
def add_tile_layer(
    self,
    url: str,
    name: Optional[str] = None,
    attribution: str = "",
    min_zoom: int = 0,
    max_zoom: int = 22,
    opacity: float = 1.0,
    **kwargs,
) -> None:
    """Add an XYZ tile layer.

    Args:
        url: Tile URL template with {x}, {y}, {z} placeholders.
        name: Layer name.
        attribution: Attribution text.
        min_zoom: Minimum zoom level.
        max_zoom: Maximum zoom level.
        opacity: Layer opacity.
        **kwargs: Additional options.
    """
    layer_id = name or f"tiles-{len(self._layers)}"

    self.call_js_method(
        "addTileLayer",
        url,
        name=layer_id,
        attribution=attribution,
        minZoom=min_zoom,
        maxZoom=max_zoom,
        opacity=opacity,
        **kwargs,
    )

    # Track layer
    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "tile",
        },
    }

add_vector(self, data, style=None, name=None, fit_bounds=True, **kwargs)

Add vector data to the map.

Supports GeoJSON, GeoDataFrame, or file paths to vector formats.

Parameters:

Name Type Description Default
data Any

GeoJSON dict, GeoDataFrame, or path to vector file.

required
style Optional[Dict]

Leaflet style properties.

None
name Optional[str]

Layer name.

None
fit_bounds bool

Whether to fit map to data bounds.

True
**kwargs

Additional layer options.

{}
Source code in anymap_ts/leaflet.py
def add_vector(
    self,
    data: Any,
    style: Optional[Dict] = None,
    name: Optional[str] = None,
    fit_bounds: bool = True,
    **kwargs,
) -> None:
    """Add vector data to the map.

    Supports GeoJSON, GeoDataFrame, or file paths to vector formats.

    Args:
        data: GeoJSON dict, GeoDataFrame, or path to vector file.
        style: Leaflet style properties.
        name: Layer name.
        fit_bounds: Whether to fit map to data bounds.
        **kwargs: Additional layer options.
    """
    geojson = to_geojson(data)

    # Handle URL data
    if geojson.get("type") == "url":
        self.add_geojson(
            geojson["url"],
            style=style,
            name=name,
            fit_bounds=fit_bounds,
            **kwargs,
        )
        return

    layer_id = name or f"vector-{len(self._layers)}"

    # Get default style if not provided
    if style is None:
        layer_type = _infer_leaflet_type(geojson)
        style = _get_default_style(layer_type)

    # Get bounds
    bounds = get_bounds(data) if fit_bounds else None

    # Call JavaScript
    self.call_js_method(
        "addGeoJSON",
        data=geojson,
        name=layer_id,
        style=style,
        fitBounds=fit_bounds,
        bounds=bounds,
        **kwargs,
    )

    # Track layer
    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "geojson",
            "style": style,
        },
    }

remove_control(self, control_type)

Remove a map control.

Parameters:

Name Type Description Default
control_type str

Type of control to remove.

required
Source code in anymap_ts/leaflet.py
def remove_control(self, control_type: str) -> None:
    """Remove a map control.

    Args:
        control_type: Type of control to remove.
    """
    self.call_js_method("removeControl", control_type)
    if control_type in self._controls:
        controls = dict(self._controls)
        del controls[control_type]
        self._controls = controls

remove_layer(self, layer_id)

Remove a layer from the map.

Parameters:

Name Type Description Default
layer_id str

Layer identifier to remove.

required
Source code in anymap_ts/leaflet.py
def remove_layer(self, layer_id: str) -> None:
    """Remove a layer from the map.

    Args:
        layer_id: Layer identifier to remove.
    """
    if layer_id in self._layers:
        layers = dict(self._layers)
        del layers[layer_id]
        self._layers = layers
    self.call_js_method("removeLayer", layer_id)

remove_marker(self, marker_id)

Remove a marker from the map.

Parameters:

Name Type Description Default
marker_id str

Marker ID to remove.

required
Source code in anymap_ts/leaflet.py
def remove_marker(self, marker_id: str) -> None:
    """Remove a marker from the map.

    Args:
        marker_id: Marker ID to remove.
    """
    self.call_js_method("removeMarker", marker_id)

set_opacity(self, layer_id, opacity)

Set layer opacity.

Parameters:

Name Type Description Default
layer_id str

Layer identifier.

required
opacity float

Opacity value between 0 and 1.

required
Source code in anymap_ts/leaflet.py
def set_opacity(self, layer_id: str, opacity: float) -> None:
    """Set layer opacity.

    Args:
        layer_id: Layer identifier.
        opacity: Opacity value between 0 and 1.
    """
    self.call_js_method("setOpacity", layer_id, opacity)

set_visibility(self, layer_id, visible)

Set layer visibility.

Parameters:

Name Type Description Default
layer_id str

Layer identifier.

required
visible bool

Whether layer should be visible.

required
Source code in anymap_ts/leaflet.py
def set_visibility(self, layer_id: str, visible: bool) -> None:
    """Set layer visibility.

    Args:
        layer_id: Layer identifier.
        visible: Whether layer should be visible.
    """
    self.call_js_method("setVisibility", layer_id, visible)

mapbox

Mapbox GL JS map widget implementation.

MapboxMap (MapWidget)

Interactive map widget using Mapbox GL JS.

This class provides a Python interface to Mapbox GL JS maps with full bidirectional communication through anywidget.

Note

Requires a Mapbox access token. Set via MAPBOX_TOKEN environment variable or pass directly to the constructor.

Examples:

>>> from anymap_ts import MapboxMap
>>> m = MapboxMap(center=[-122.4, 37.8], zoom=10)
>>> m.add_basemap("mapbox://styles/mapbox/streets-v12")
>>> m
Source code in anymap_ts/mapbox.py
class MapboxMap(MapWidget):
    """Interactive map widget using Mapbox GL JS.

    This class provides a Python interface to Mapbox GL JS maps with
    full bidirectional communication through anywidget.

    Note:
        Requires a Mapbox access token. Set via MAPBOX_TOKEN environment
        variable or pass directly to the constructor.

    Example:
        >>> from anymap_ts import MapboxMap
        >>> m = MapboxMap(center=[-122.4, 37.8], zoom=10)
        >>> m.add_basemap("mapbox://styles/mapbox/streets-v12")
        >>> m
    """

    # ESM module for frontend
    _esm = STATIC_DIR / "mapbox.js"
    _css = STATIC_DIR / "mapbox.css"

    # Mapbox-specific traits
    access_token = traitlets.Unicode("").tag(sync=True)
    bearing = traitlets.Float(0.0).tag(sync=True)
    pitch = traitlets.Float(0.0).tag(sync=True)
    antialias = traitlets.Bool(True).tag(sync=True)
    double_click_zoom = traitlets.Bool(True).tag(sync=True)

    # Layer tracking
    _layer_dict = traitlets.Dict({}).tag(sync=True)

    def __init__(
        self,
        center: Tuple[float, float] = (0.0, 0.0),
        zoom: float = 2.0,
        width: str = "100%",
        height: str = "600px",
        style: str = "mapbox://styles/mapbox/streets-v12",
        bearing: float = 0.0,
        pitch: float = 0.0,
        max_pitch: float = 85.0,
        access_token: Optional[str] = None,
        controls: Optional[Dict[str, Any]] = None,
        **kwargs,
    ):
        """Initialize a Mapbox map.

        Args:
            center: Map center as (longitude, latitude).
            zoom: Initial zoom level.
            width: Map width as CSS string.
            height: Map height as CSS string.
            style: Mapbox style URL (e.g., "mapbox://styles/mapbox/streets-v12").
            bearing: Map bearing in degrees.
            pitch: Map pitch in degrees.
            max_pitch: Maximum pitch angle in degrees (default: 85).
            access_token: Mapbox access token. If None, reads from MAPBOX_TOKEN env var.
            controls: Dict of controls to add (e.g., {"navigation": True}).
            **kwargs: Additional widget arguments.
        """
        # Get access token
        token = access_token or get_mapbox_token()
        if not token:
            print(
                "Warning: No Mapbox access token provided. "
                "Set MAPBOX_TOKEN environment variable or pass access_token parameter."
            )

        super().__init__(
            center=list(center),
            zoom=zoom,
            width=width,
            height=height,
            style=style,
            bearing=bearing,
            pitch=pitch,
            max_pitch=max_pitch,
            access_token=token,
            **kwargs,
        )

        # Initialize layer dictionary
        self._layer_dict = {"Background": []}

        # Add default controls
        if controls is None:
            controls = {"navigation": True, "fullscreen": True}

        for control_name, config in controls.items():
            if config:
                self.add_control(
                    control_name, **(config if isinstance(config, dict) else {})
                )

    def set_access_token(self, token: str) -> None:
        """Set the Mapbox access token.

        Args:
            token: Mapbox access token.
        """
        self.access_token = token

    # -------------------------------------------------------------------------
    # Layer Dict Helpers
    # -------------------------------------------------------------------------

    def _add_to_layer_dict(self, layer_id: str, category: str = "Overlays") -> None:
        """Add a layer to the layer dictionary for UI tracking."""
        layers = self._layer_dict.get(category, [])
        if layer_id not in layers:
            self._layer_dict = {
                **self._layer_dict,
                category: layers + [layer_id],
            }

    def _remove_from_layer_dict(self, layer_id: str) -> None:
        """Remove a layer from the layer dictionary."""
        new_dict = {}
        for category, layers in self._layer_dict.items():
            if layer_id in layers:
                new_layers = [lid for lid in layers if lid != layer_id]
                if new_layers:
                    new_dict[category] = new_layers
            else:
                new_dict[category] = layers
        self._layer_dict = new_dict

    def _validate_opacity(self, opacity: float, param_name: str = "opacity") -> float:
        """Validate opacity value is between 0 and 1."""
        if not 0 <= opacity <= 1:
            raise ValueError(f"{param_name} must be between 0 and 1, got {opacity}")
        return opacity

    def _validate_position(self, position: str) -> str:
        """Validate control position is valid."""
        valid_positions = ["top-left", "top-right", "bottom-left", "bottom-right"]
        if position not in valid_positions:
            raise ValueError(
                f"Position must be one of: {', '.join(valid_positions)}, got '{position}'"
            )
        return position

    def _remove_layer_internal(self, layer_id: str, js_method: str) -> None:
        """Internal helper to remove a layer."""
        if layer_id in self._layers:
            layers = dict(self._layers)
            del layers[layer_id]
            self._layers = layers
        self._remove_from_layer_dict(layer_id)
        self.call_js_method(js_method, layer_id)

    # -------------------------------------------------------------------------
    # Basemap Methods
    # -------------------------------------------------------------------------

    def add_basemap(
        self,
        basemap: str = "mapbox://styles/mapbox/streets-v12",
        attribution: Optional[str] = None,
        **kwargs,
    ) -> None:
        """Add a basemap layer.

        For Mapbox styles, use the style URL format:
        - "mapbox://styles/mapbox/streets-v12"
        - "mapbox://styles/mapbox/satellite-v9"
        - "mapbox://styles/mapbox/satellite-streets-v12"
        - "mapbox://styles/mapbox/light-v11"
        - "mapbox://styles/mapbox/dark-v11"
        - "mapbox://styles/mapbox/outdoors-v12"

        Or use XYZ tile URLs for custom basemaps.

        Args:
            basemap: Mapbox style URL or XYZ tile URL.
            attribution: Custom attribution text.
            **kwargs: Additional options.
        """
        # If it's a Mapbox style URL, set it as the map style
        if basemap.startswith("mapbox://"):
            self.style = basemap
            return

        # Otherwise, treat as XYZ tile URL
        try:
            url, default_attribution = get_basemap_url(basemap)
        except (ValueError, KeyError):
            url = basemap
            default_attribution = ""

        self.call_js_method(
            "addBasemap",
            url,
            attribution=attribution or default_attribution,
            name=basemap,
            **kwargs,
        )

        # Track in layer dict
        basemaps = self._layer_dict.get("Basemaps", [])
        if basemap not in basemaps:
            self._layer_dict = {
                **self._layer_dict,
                "Basemaps": basemaps + [basemap],
            }

    # -------------------------------------------------------------------------
    # Vector Data Methods
    # -------------------------------------------------------------------------

    def add_vector(
        self,
        data: Any,
        layer_type: Optional[str] = None,
        paint: Optional[Dict] = None,
        name: Optional[str] = None,
        fit_bounds: bool = True,
        **kwargs,
    ) -> None:
        """Add vector data to the map.

        Supports GeoJSON, GeoDataFrame, or file paths to vector formats.

        Args:
            data: GeoJSON dict, GeoDataFrame, or path to vector file.
            layer_type: Mapbox layer type ('circle', 'line', 'fill', 'symbol').
            paint: Mapbox paint properties.
            name: Layer name.
            fit_bounds: Whether to fit map to data bounds.
            **kwargs: Additional layer options.
        """
        geojson = to_geojson(data)

        layer_id = name or f"vector-{len(self._layers)}"

        # Handle URL data - fetch GeoJSON to get bounds and infer layer type
        if geojson.get("type") == "url":
            url = geojson["url"]
            geojson = fetch_geojson(url)

        # Infer layer type if not specified
        if layer_type is None:
            layer_type = infer_layer_type(geojson)

        # Get default paint if not provided
        if paint is None:
            paint = get_default_paint(layer_type)

        # Get bounds (use geojson dict, not original data which may be a URL)
        bounds = get_bounds(geojson) if fit_bounds else None

        # Call JavaScript
        self.call_js_method(
            "addGeoJSON",
            data=geojson,
            name=layer_id,
            layerType=layer_type,
            paint=paint,
            fitBounds=fit_bounds,
            bounds=bounds,
            **kwargs,
        )

        # Track layer
        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": layer_type,
                "source": f"{layer_id}-source",
                "paint": paint,
            },
        }
        self._add_to_layer_dict(layer_id, "Vector")

    def add_geojson(
        self,
        data: Union[str, Dict],
        layer_type: Optional[str] = None,
        paint: Optional[Dict] = None,
        name: Optional[str] = None,
        fit_bounds: bool = True,
        **kwargs,
    ) -> None:
        """Add GeoJSON data to the map.

        Args:
            data: GeoJSON dict or URL to GeoJSON file.
            layer_type: Mapbox layer type.
            paint: Mapbox paint properties.
            name: Layer name.
            fit_bounds: Whether to fit map to data bounds.
            **kwargs: Additional layer options.
        """
        self.add_vector(
            data,
            layer_type=layer_type,
            paint=paint,
            name=name,
            fit_bounds=fit_bounds,
            **kwargs,
        )

    # -------------------------------------------------------------------------
    # Raster Data Methods
    # -------------------------------------------------------------------------

    def add_tile_layer(
        self,
        url: str,
        name: Optional[str] = None,
        attribution: str = "",
        min_zoom: int = 0,
        max_zoom: int = 22,
        **kwargs,
    ) -> None:
        """Add an XYZ tile layer.

        Args:
            url: Tile URL template with {x}, {y}, {z} placeholders.
            name: Layer name.
            attribution: Attribution text.
            min_zoom: Minimum zoom level.
            max_zoom: Maximum zoom level.
            **kwargs: Additional options.
        """
        layer_id = name or f"tiles-{len(self._layers)}"

        self.call_js_method(
            "addTileLayer",
            url,
            name=layer_id,
            attribution=attribution,
            minZoom=min_zoom,
            maxZoom=max_zoom,
            **kwargs,
        )

        # Track layer
        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "raster",
                "source": f"{layer_id}-source",
            },
        }
        self._add_to_layer_dict(layer_id, "Raster")

    def add_raster(
        self,
        source: str,
        name: Optional[str] = None,
        attribution: str = "",
        indexes: Optional[List[int]] = None,
        colormap: Optional[str] = None,
        vmin: Optional[float] = None,
        vmax: Optional[float] = None,
        nodata: Optional[float] = None,
        fit_bounds: bool = True,
        **kwargs,
    ) -> None:
        """Add a raster layer from a local file using localtileserver."""
        try:
            from localtileserver import TileClient
        except ImportError:
            raise ImportError(
                "localtileserver is required for local raster support. "
                "Install with: pip install anymap-ts[raster]"
            )

        client = TileClient(source)

        tile_params = {}
        if indexes:
            tile_params["indexes"] = indexes
        if colormap:
            tile_params["colormap"] = colormap
        if vmin is not None or vmax is not None:
            tile_params["vmin"] = vmin if vmin is not None else client.min
            tile_params["vmax"] = vmax if vmax is not None else client.max
        if nodata is not None:
            tile_params["nodata"] = nodata

        tile_url = client.get_tile_url(**tile_params)

        layer_name = name or Path(source).stem

        self.add_tile_layer(
            tile_url,
            name=layer_name,
            attribution=attribution,
            **kwargs,
        )

        if fit_bounds:
            bounds = client.bounds()
            if bounds:
                self.fit_bounds([bounds[0], bounds[1], bounds[2], bounds[3]])

    def add_stac_layer(
        self,
        url: Optional[str] = None,
        item: Optional[Any] = None,
        assets: Optional[List[str]] = None,
        colormap: Optional[str] = None,
        rescale: Optional[List[float]] = None,
        opacity: float = 1.0,
        layer_id: Optional[str] = None,
        titiler_endpoint: str = "https://titiler.xyz",
        attribution: str = "STAC",
        fit_bounds: bool = True,
        **kwargs,
    ) -> None:
        """Add a STAC (SpatioTemporal Asset Catalog) layer to the map."""
        if url is None and item is None:
            raise ValueError("Either 'url' or 'item' must be provided")

        if url is not None and item is not None:
            raise ValueError("Provide either 'url' or 'item', not both")

        if item is not None:
            try:
                if hasattr(item, "to_dict") and hasattr(item, "self_href"):
                    stac_url = item.self_href
                    if not stac_url and hasattr(item, "links"):
                        for link in item.links:
                            if link.rel == "self":
                                stac_url = link.href
                                break
                    if not stac_url:
                        raise ValueError("STAC item must have a self_href or self link")
                else:
                    raise ValueError(
                        "Item must be a pystac Item object with to_dict() and self_href"
                    )
            except Exception as e:
                raise ValueError(f"Invalid STAC item: {e}")
        else:
            stac_url = url

        tile_params = {"url": stac_url}
        if assets:
            tile_params["assets"] = ",".join(assets)
        if colormap:
            tile_params["colormap_name"] = colormap
        if rescale:
            if len(rescale) == 2:
                tile_params["rescale"] = f"{rescale[0]},{rescale[1]}"
            else:
                raise ValueError("rescale must be a list of two values [min, max]")

        query_string = urlencode(tile_params)
        tile_url = f"{titiler_endpoint.rstrip('/')}/stac/tiles/{{z}}/{{x}}/{{y}}?{query_string}"

        layer_name = layer_id or f"stac-{len(self._layers)}"

        self.add_tile_layer(
            url=tile_url,
            name=layer_name,
            attribution=attribution,
            **kwargs,
        )

        if fit_bounds and item is not None:
            try:
                bbox = item.bbox
                if bbox and len(bbox) == 4:
                    self.fit_bounds([[bbox[0], bbox[1]], [bbox[2], bbox[3]]])
            except Exception:
                pass

    # -------------------------------------------------------------------------
    # COG Layer (deck.gl)
    # -------------------------------------------------------------------------

    def add_heatmap(
        self,
        data: Any,
        weight_property: Optional[str] = None,
        radius: int = 20,
        intensity: float = 1.0,
        colormap: Optional[List] = None,
        opacity: float = 0.8,
        name: Optional[str] = None,
        fit_bounds: bool = True,
        **kwargs,
    ) -> None:
        """Add a heatmap layer to the map."""
        self._validate_opacity(opacity)
        layer_id = name or f"heatmap-{len(self._layers)}"

        geojson = to_geojson(data)

        if geojson.get("type") == "url":
            url = geojson["url"]
            geojson = fetch_geojson(url)

        if colormap is None:
            colormap = [
                [0, "rgba(33,102,172,0)"],
                [0.2, "rgb(103,169,207)"],
                [0.4, "rgb(209,229,240)"],
                [0.6, "rgb(253,219,199)"],
                [0.8, "rgb(239,138,98)"],
                [1, "rgb(178,24,43)"],
            ]

        paint = {
            "heatmap-radius": radius,
            "heatmap-intensity": intensity,
            "heatmap-opacity": opacity,
            "heatmap-color": [
                "interpolate",
                ["linear"],
                ["heatmap-density"],
            ],
        }

        for stop, color in colormap:
            paint["heatmap-color"].extend([stop, color])

        if weight_property:
            paint["heatmap-weight"] = ["get", weight_property]

        bounds = get_bounds(geojson) if fit_bounds else None

        self.call_js_method(
            "addGeoJSON",
            data=geojson,
            name=layer_id,
            layerType="heatmap",
            paint=paint,
            fitBounds=fit_bounds,
            bounds=bounds,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "heatmap",
                "source": f"{layer_id}-source",
                "paint": paint,
            },
        }
        self._add_to_layer_dict(layer_id, "Heatmap")

    def add_cog_layer(
        self,
        url: str,
        name: Optional[str] = None,
        opacity: float = 1.0,
        visible: bool = True,
        debug: bool = False,
        debug_opacity: float = 0.25,
        max_error: float = 0.125,
        fit_bounds: bool = True,
        before_id: Optional[str] = None,
        **kwargs,
    ) -> None:
        """Add a Cloud Optimized GeoTIFF (COG) layer using deck.gl-raster.

        This method renders COG files directly in the browser using GPU-accelerated
        deck.gl rendering with automatic reprojection support.

        Args:
            url: URL to the Cloud Optimized GeoTIFF file.
            name: Layer ID. If None, auto-generated.
            opacity: Layer opacity (0-1).
            visible: Whether layer is visible.
            debug: Show reprojection mesh for debugging.
            debug_opacity: Opacity of debug mesh (0-1).
            max_error: Maximum reprojection error in pixels. Lower values
                create denser mesh for better accuracy.
            fit_bounds: Whether to fit map to COG bounds after loading.
            before_id: ID of layer to insert before.
            **kwargs: Additional COGLayer props.

        Example:
            >>> from anymap_ts import MapboxMap
            >>> m = MapboxMap()
            >>> m.add_cog_layer(
            ...     "https://example.com/landcover.tif",
            ...     name="landcover",
            ...     opacity=0.8
            ... )
        """
        layer_id = name or f"cog-{len(self._layers)}"

        self.call_js_method(
            "addCOGLayer",
            id=layer_id,
            geotiff=url,
            opacity=opacity,
            visible=visible,
            debug=debug,
            debugOpacity=debug_opacity,
            maxError=max_error,
            fitBounds=fit_bounds,
            beforeId=before_id,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "cog",
                "url": url,
            },
        }
        self._add_to_layer_dict(layer_id, "Raster")

    def remove_cog_layer(self, layer_id: str) -> None:
        """Remove a COG layer."""
        self._remove_layer_internal(layer_id, "removeCOGLayer")

    def add_zarr_layer(
        self,
        url: str,
        variable: str,
        name: Optional[str] = None,
        colormap: Optional[List[str]] = None,
        clim: Optional[Tuple[float, float]] = None,
        opacity: float = 1.0,
        selector: Optional[Dict[str, Any]] = None,
        minzoom: int = 0,
        maxzoom: int = 22,
        fill_value: Optional[float] = None,
        spatial_dimensions: Optional[Dict[str, str]] = None,
        zarr_version: Optional[int] = None,
        bounds: Optional[List[float]] = None,
        **kwargs,
    ) -> None:
        """Add a Zarr dataset layer for visualizing multidimensional array data."""
        layer_id = name or f"zarr-{len(self._layers)}"

        self.call_js_method(
            "addZarrLayer",
            id=layer_id,
            source=url,
            variable=variable,
            colormap=colormap or ["#000000", "#ffffff"],
            clim=list(clim) if clim else [0, 100],
            opacity=opacity,
            selector=selector or {},
            minzoom=minzoom,
            maxzoom=maxzoom,
            fillValue=fill_value,
            spatialDimensions=spatial_dimensions,
            zarrVersion=zarr_version,
            bounds=bounds,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "zarr",
                "url": url,
                "variable": variable,
            },
        }
        self._add_to_layer_dict(layer_id, "Raster")

    def remove_zarr_layer(self, layer_id: str) -> None:
        """Remove a Zarr layer."""
        self._remove_layer_internal(layer_id, "removeZarrLayer")

    def update_zarr_layer(
        self,
        layer_id: str,
        selector: Optional[Dict[str, Any]] = None,
        clim: Optional[Tuple[float, float]] = None,
        colormap: Optional[List[str]] = None,
        opacity: Optional[float] = None,
    ) -> None:
        """Update a Zarr layer's properties dynamically."""
        update_kwargs: Dict[str, Any] = {"id": layer_id}
        if selector is not None:
            update_kwargs["selector"] = selector
        if clim is not None:
            update_kwargs["clim"] = list(clim)
        if colormap is not None:
            update_kwargs["colormap"] = colormap
        if opacity is not None:
            update_kwargs["opacity"] = opacity
        self.call_js_method("updateZarrLayer", **update_kwargs)

    def add_pmtiles_layer(
        self,
        url: str,
        layer_id: Optional[str] = None,
        style: Optional[Dict[str, Any]] = None,
        opacity: float = 1.0,
        visible: bool = True,
        fit_bounds: bool = False,
        source_type: str = "vector",
        **kwargs,
    ) -> None:
        """Add a PMTiles layer for efficient vector or raster tile serving."""
        layer_id = layer_id or f"pmtiles-{len(self._layers)}"

        self.call_js_method(
            "addPMTilesLayer",
            url=url,
            id=layer_id,
            style=style or {},
            opacity=opacity,
            visible=visible,
            fitBounds=fit_bounds,
            sourceType=source_type,
            name=layer_id,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "pmtiles",
                "url": url,
                "source_type": source_type,
            },
        }
        category = "Vector" if source_type == "vector" else "Raster"
        self._add_to_layer_dict(layer_id, category)

    def remove_pmtiles_layer(self, layer_id: str) -> None:
        """Remove a PMTiles layer."""
        self._remove_layer_internal(layer_id, "removePMTilesLayer")

    # -------------------------------------------------------------------------
    # Arc Layer (deck.gl)
    # -------------------------------------------------------------------------

    def add_arc_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_source_position: Union[str, Any] = "source",
        get_target_position: Union[str, Any] = "target",
        get_source_color: Optional[List[int]] = None,
        get_target_color: Optional[List[int]] = None,
        get_width: Union[float, str] = 1,
        get_height: float = 1,
        great_circle: bool = False,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add an arc layer for origin-destination visualization using deck.gl.

        Arc layers are ideal for visualizing connections between locations,
        such as flight routes, migration patterns, or network flows.

        Args:
            data: Array of data objects with source/target coordinates.
                Each object should have source and target positions.
            name: Layer ID. If None, auto-generated.
            get_source_position: Accessor for source position [lng, lat].
                Can be a string (property name) or a value.
            get_target_position: Accessor for target position [lng, lat].
                Can be a string (property name) or a value.
            get_source_color: Source end color as [r, g, b, a].
                Default: [51, 136, 255, 255] (blue).
            get_target_color: Target end color as [r, g, b, a].
                Default: [255, 136, 51, 255] (orange).
            get_width: Arc width in pixels. Can be a number or accessor.
            get_height: Arc height multiplier. Higher values create more curved arcs.
            great_circle: Whether to draw arcs along great circles.
            pickable: Whether layer responds to hover/click events.
            opacity: Layer opacity (0-1).
            **kwargs: Additional ArcLayer props.

        Example:
            >>> from anymap_ts import MapboxMap
            >>> m = MapboxMap()
            >>> arcs = [
            ...     {"source": [-122.4, 37.8], "target": [-73.9, 40.7]},
            ...     {"source": [-122.4, 37.8], "target": [-0.1, 51.5]},
            ... ]
            >>> m.add_arc_layer(arcs, name="flights")
        """
        layer_id = name or f"arc-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addArcLayer",
            id=layer_id,
            data=processed_data,
            getSourcePosition=get_source_position,
            getTargetPosition=get_target_position,
            getSourceColor=get_source_color or [51, 136, 255, 255],
            getTargetColor=get_target_color or [255, 136, 51, 255],
            getWidth=get_width,
            getHeight=get_height,
            greatCircle=great_circle,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "arc",
            },
        }
        self._add_to_layer_dict(layer_id, "Deck.gl")

    def remove_arc_layer(self, layer_id: str) -> None:
        """Remove an arc layer."""
        self._remove_layer_internal(layer_id, "removeArcLayer")

    # -------------------------------------------------------------------------
    # PointCloud Layer (deck.gl)
    # -------------------------------------------------------------------------

    def add_point_cloud_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_position: Union[str, Any] = "position",
        get_color: Optional[Union[List[int], str]] = None,
        get_normal: Optional[Union[str, Any]] = None,
        point_size: float = 2,
        size_units: str = "pixels",
        pickable: bool = True,
        opacity: float = 1.0,
        material: bool = True,
        coordinate_system: Optional[int] = None,
        coordinate_origin: Optional[List[float]] = None,
        **kwargs,
    ) -> None:
        """Add a point cloud layer for 3D point visualization using deck.gl.

        Point cloud layers render large collections of 3D points, ideal for
        LiDAR data, photogrammetry outputs, or any 3D point dataset.

        Args:
            data: Array of point data with positions. Each point should have
                x, y, z coordinates (or position array).
            name: Layer ID. If None, auto-generated.
            get_position: Accessor for point position [x, y, z].
                Can be a string (property name) or a value.
            get_color: Accessor or value for point color [r, g, b, a].
                Default: [255, 255, 255, 255] (white).
            get_normal: Accessor for point normal [nx, ny, nz] for lighting.
                Default: [0, 0, 1] (pointing up).
            point_size: Point size in pixels or meters (depends on size_units).
            size_units: Size units: 'pixels', 'meters', or 'common'.
            pickable: Whether layer responds to hover/click events.
            opacity: Layer opacity (0-1).
            material: Whether to enable lighting effects.
            coordinate_system: Coordinate system for positions.
            coordinate_origin: Origin for coordinate system [x, y, z].
            **kwargs: Additional PointCloudLayer props.

        Example:
            >>> from anymap_ts import MapboxMap
            >>> m = MapboxMap(pitch=45)
            >>> points = [
            ...     {"position": [-122.4, 37.8, 100], "color": [255, 0, 0, 255]},
            ...     {"position": [-122.3, 37.7, 200], "color": [0, 255, 0, 255]},
            ... ]
            >>> m.add_point_cloud_layer(points, point_size=5)
        """
        layer_id = name or f"pointcloud-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addPointCloudLayer",
            id=layer_id,
            data=processed_data,
            getPosition=get_position,
            getColor=get_color or [255, 255, 255, 255],
            getNormal=get_normal,
            pointSize=point_size,
            sizeUnits=size_units,
            pickable=pickable,
            opacity=opacity,
            material=material,
            coordinateSystem=coordinate_system,
            coordinateOrigin=coordinate_origin,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "pointcloud",
            },
        }
        self._add_to_layer_dict(layer_id, "Deck.gl")

    def remove_point_cloud_layer(self, layer_id: str) -> None:
        """Remove a point cloud layer."""
        self._remove_layer_internal(layer_id, "removePointCloudLayer")

    def add_scatterplot_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_position: Union[str, Any] = "coordinates",
        get_radius: Union[float, str] = 5,
        get_fill_color: Optional[Union[List[int], str]] = None,
        get_line_color: Optional[Union[List[int], str]] = None,
        radius_scale: float = 1,
        radius_min_pixels: float = 1,
        radius_max_pixels: float = 100,
        line_width_min_pixels: float = 1,
        stroked: bool = True,
        filled: bool = True,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add a scatterplot layer using deck.gl."""
        layer_id = name or f"scatterplot-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addScatterplotLayer",
            id=layer_id,
            data=processed_data,
            getPosition=get_position,
            getRadius=get_radius,
            getFillColor=get_fill_color or [51, 136, 255, 200],
            getLineColor=get_line_color or [255, 255, 255, 255],
            radiusScale=radius_scale,
            radiusMinPixels=radius_min_pixels,
            radiusMaxPixels=radius_max_pixels,
            lineWidthMinPixels=line_width_min_pixels,
            stroked=stroked,
            filled=filled,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {"id": layer_id, "type": "scatterplot"},
        }
        self._add_to_layer_dict(layer_id, "Deck.gl")

    def add_path_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_path: Union[str, Any] = "path",
        get_color: Optional[Union[List[int], str]] = None,
        get_width: Union[float, str] = 1,
        width_scale: float = 1,
        width_min_pixels: float = 1,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add a path layer using deck.gl."""
        layer_id = name or f"path-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addPathLayer",
            id=layer_id,
            data=processed_data,
            getPath=get_path,
            getColor=get_color or [51, 136, 255, 200],
            getWidth=get_width,
            widthScale=width_scale,
            widthMinPixels=width_min_pixels,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {**self._layers, layer_id: {"id": layer_id, "type": "path"}}
        self._add_to_layer_dict(layer_id, "Deck.gl")

    def add_polygon_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_polygon: Union[str, Any] = "polygon",
        get_fill_color: Optional[Union[List[int], str]] = None,
        get_line_color: Optional[Union[List[int], str]] = None,
        get_line_width: Union[float, str] = 1,
        get_elevation: Union[float, str] = 0,
        extruded: bool = False,
        wireframe: bool = False,
        filled: bool = True,
        stroked: bool = True,
        line_width_min_pixels: float = 1,
        pickable: bool = True,
        opacity: float = 0.5,
        **kwargs,
    ) -> None:
        """Add a polygon layer using deck.gl."""
        layer_id = name or f"polygon-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addPolygonLayer",
            id=layer_id,
            data=processed_data,
            getPolygon=get_polygon,
            getFillColor=get_fill_color or [51, 136, 255, 128],
            getLineColor=get_line_color or [0, 0, 255, 255],
            getLineWidth=get_line_width,
            getElevation=get_elevation,
            extruded=extruded,
            wireframe=wireframe,
            filled=filled,
            stroked=stroked,
            lineWidthMinPixels=line_width_min_pixels,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {**self._layers, layer_id: {"id": layer_id, "type": "polygon"}}
        self._add_to_layer_dict(layer_id, "Deck.gl")

    def add_hexagon_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_position: Union[str, Any] = "coordinates",
        radius: float = 1000,
        elevation_scale: float = 4,
        extruded: bool = True,
        color_range: Optional[List[List[int]]] = None,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add a hexagon layer using deck.gl."""
        layer_id = name or f"hexagon-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        default_color_range = [
            [1, 152, 189],
            [73, 227, 206],
            [216, 254, 181],
            [254, 237, 177],
            [254, 173, 84],
            [209, 55, 78],
        ]

        self.call_js_method(
            "addHexagonLayer",
            id=layer_id,
            data=processed_data,
            getPosition=get_position,
            radius=radius,
            elevationScale=elevation_scale,
            extruded=extruded,
            colorRange=color_range or default_color_range,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {**self._layers, layer_id: {"id": layer_id, "type": "hexagon"}}
        self._add_to_layer_dict(layer_id, "Deck.gl")

    def add_deck_heatmap_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_position: Union[str, Any] = "coordinates",
        get_weight: Union[float, str] = 1,
        radius_pixels: float = 30,
        intensity: float = 1,
        threshold: float = 0.05,
        color_range: Optional[List[List[int]]] = None,
        opacity: float = 1,
        **kwargs,
    ) -> None:
        """Add a GPU-accelerated heatmap layer using deck.gl."""
        layer_id = name or f"deck-heatmap-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        default_color_range = [
            [255, 255, 178, 25],
            [254, 217, 118, 85],
            [254, 178, 76, 127],
            [253, 141, 60, 170],
            [240, 59, 32, 212],
            [189, 0, 38, 255],
        ]

        self.call_js_method(
            "addHeatmapLayer",
            id=layer_id,
            data=processed_data,
            getPosition=get_position,
            getWeight=get_weight,
            radiusPixels=radius_pixels,
            intensity=intensity,
            threshold=threshold,
            colorRange=color_range or default_color_range,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {"id": layer_id, "type": "deck-heatmap"},
        }
        self._add_to_layer_dict(layer_id, "Deck.gl")

    def add_grid_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_position: Union[str, Any] = "coordinates",
        cell_size: float = 200,
        elevation_scale: float = 4,
        extruded: bool = True,
        color_range: Optional[List[List[int]]] = None,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add a grid layer using deck.gl."""
        layer_id = name or f"grid-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        default_color_range = [
            [1, 152, 189],
            [73, 227, 206],
            [216, 254, 181],
            [254, 237, 177],
            [254, 173, 84],
            [209, 55, 78],
        ]

        self.call_js_method(
            "addGridLayer",
            id=layer_id,
            data=processed_data,
            getPosition=get_position,
            cellSize=cell_size,
            elevationScale=elevation_scale,
            extruded=extruded,
            colorRange=color_range or default_color_range,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {**self._layers, layer_id: {"id": layer_id, "type": "grid"}}
        self._add_to_layer_dict(layer_id, "Deck.gl")

    def add_icon_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_position: Union[str, Any] = "coordinates",
        get_icon: Union[str, Any] = "icon",
        get_size: Union[float, str] = 20,
        get_color: Optional[Union[List[int], str]] = None,
        icon_atlas: Optional[str] = None,
        icon_mapping: Optional[Dict] = None,
        pickable: bool = True,
        opacity: float = 1,
        **kwargs,
    ) -> None:
        """Add an icon layer using deck.gl."""
        layer_id = name or f"icon-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addIconLayer",
            id=layer_id,
            data=processed_data,
            getPosition=get_position,
            getIcon=get_icon,
            getSize=get_size,
            getColor=get_color or [255, 255, 255, 255],
            iconAtlas=icon_atlas,
            iconMapping=icon_mapping,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {**self._layers, layer_id: {"id": layer_id, "type": "icon"}}
        self._add_to_layer_dict(layer_id, "Deck.gl")

    def add_text_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_position: Union[str, Any] = "coordinates",
        get_text: Union[str, Any] = "text",
        get_size: Union[float, str] = 12,
        get_color: Optional[Union[List[int], str]] = None,
        get_angle: Union[float, str] = 0,
        text_anchor: str = "middle",
        alignment_baseline: str = "center",
        pickable: bool = True,
        opacity: float = 1,
        **kwargs,
    ) -> None:
        """Add a text layer using deck.gl."""
        layer_id = name or f"text-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addTextLayer",
            id=layer_id,
            data=processed_data,
            getPosition=get_position,
            getText=get_text,
            getSize=get_size,
            getColor=get_color or [0, 0, 0, 255],
            getAngle=get_angle,
            getTextAnchor=text_anchor,
            getAlignmentBaseline=alignment_baseline,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {**self._layers, layer_id: {"id": layer_id, "type": "text"}}
        self._add_to_layer_dict(layer_id, "Deck.gl")

    def add_geojson_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_fill_color: Optional[Union[List[int], str]] = None,
        get_line_color: Optional[Union[List[int], str]] = None,
        get_line_width: Union[float, str] = 1,
        get_point_radius: Union[float, str] = 5,
        get_elevation: Union[float, str] = 0,
        extruded: bool = False,
        wireframe: bool = False,
        filled: bool = True,
        stroked: bool = True,
        line_width_min_pixels: float = 1,
        point_radius_min_pixels: float = 2,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add a GeoJSON layer with auto-styling using deck.gl."""
        layer_id = name or f"geojson-deck-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addGeoJsonLayer",
            id=layer_id,
            data=processed_data,
            getFillColor=get_fill_color or [51, 136, 255, 128],
            getLineColor=get_line_color or [0, 0, 0, 255],
            getLineWidth=get_line_width,
            getPointRadius=get_point_radius,
            getElevation=get_elevation,
            extruded=extruded,
            wireframe=wireframe,
            filled=filled,
            stroked=stroked,
            lineWidthMinPixels=line_width_min_pixels,
            pointRadiusMinPixels=point_radius_min_pixels,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {"id": layer_id, "type": "geojson-deck"},
        }
        self._add_to_layer_dict(layer_id, "Deck.gl")

    def add_contour_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_position: Union[str, Any] = "coordinates",
        get_weight: Union[float, str] = 1,
        cell_size: float = 200,
        contours: Optional[List[Dict]] = None,
        pickable: bool = True,
        opacity: float = 1,
        **kwargs,
    ) -> None:
        """Add a contour layer using deck.gl."""
        layer_id = name or f"contour-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        default_contours = [
            {"threshold": 1, "color": [255, 255, 255], "strokeWidth": 1},
            {"threshold": 5, "color": [51, 136, 255], "strokeWidth": 2},
            {"threshold": 10, "color": [0, 0, 255], "strokeWidth": 3},
        ]

        self.call_js_method(
            "addContourLayer",
            id=layer_id,
            data=processed_data,
            getPosition=get_position,
            getWeight=get_weight,
            cellSize=cell_size,
            contours=contours or default_contours,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {**self._layers, layer_id: {"id": layer_id, "type": "contour"}}
        self._add_to_layer_dict(layer_id, "Deck.gl")

    def add_screen_grid_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_position: Union[str, Any] = "coordinates",
        get_weight: Union[float, str] = 1,
        cell_size_pixels: float = 50,
        color_range: Optional[List[List[int]]] = None,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add a screen grid layer using deck.gl."""
        layer_id = name or f"screengrid-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        default_color_range = [
            [255, 255, 178, 25],
            [254, 217, 118, 85],
            [254, 178, 76, 127],
            [253, 141, 60, 170],
            [240, 59, 32, 212],
            [189, 0, 38, 255],
        ]

        self.call_js_method(
            "addScreenGridLayer",
            id=layer_id,
            data=processed_data,
            getPosition=get_position,
            getWeight=get_weight,
            cellSizePixels=cell_size_pixels,
            colorRange=color_range or default_color_range,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {"id": layer_id, "type": "screengrid"},
        }
        self._add_to_layer_dict(layer_id, "Deck.gl")

    def add_trips_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_path: Union[str, Any] = "waypoints",
        get_timestamps: Union[str, Any] = "timestamps",
        get_color: Optional[Union[List[int], str]] = None,
        width_min_pixels: float = 2,
        trail_length: float = 180,
        current_time: float = 0,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add a trips layer using deck.gl."""
        layer_id = name or f"trips-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addTripsLayer",
            id=layer_id,
            data=processed_data,
            getPath=get_path,
            getTimestamps=get_timestamps,
            getColor=get_color or [253, 128, 93],
            widthMinPixels=width_min_pixels,
            trailLength=trail_length,
            currentTime=current_time,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {**self._layers, layer_id: {"id": layer_id, "type": "trips"}}
        self._add_to_layer_dict(layer_id, "Deck.gl")

    def add_line_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_source_position: Union[str, Any] = "sourcePosition",
        get_target_position: Union[str, Any] = "targetPosition",
        get_color: Optional[Union[List[int], str]] = None,
        get_width: Union[float, str] = 1,
        width_min_pixels: float = 1,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add a line layer using deck.gl."""
        layer_id = name or f"line-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addLineLayer",
            id=layer_id,
            data=processed_data,
            getSourcePosition=get_source_position,
            getTargetPosition=get_target_position,
            getColor=get_color or [51, 136, 255, 200],
            getWidth=get_width,
            widthMinPixels=width_min_pixels,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {**self._layers, layer_id: {"id": layer_id, "type": "line"}}
        self._add_to_layer_dict(layer_id, "Deck.gl")

    def add_deckgl_layer(
        self,
        layer_type: str,
        data: Any,
        name: Optional[str] = None,
        **kwargs,
    ) -> None:
        """Add a generic deck.gl layer to the map."""
        layer_type_clean = layer_type.replace("Layer", "")
        prefix = layer_type_clean.lower()
        layer_id = name or f"{prefix}-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addDeckGLLayer",
            layerType=layer_type,
            id=layer_id,
            data=processed_data,
            **kwargs,
        )

        self._layers = {**self._layers, layer_id: {"id": layer_id, "type": layer_type}}
        self._add_to_layer_dict(layer_id, "Deck.gl")

    def remove_deck_layer(self, layer_id: str) -> None:
        """Remove a deck.gl layer from the map."""
        self._remove_layer_internal(layer_id, "removeDeckLayer")

    def add_column_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_position: Union[str, Any] = "coordinates",
        get_fill_color: Optional[Union[List[int], str]] = None,
        get_line_color: Optional[Union[List[int], str]] = None,
        get_elevation: Union[float, str] = 1000,
        radius: float = 1000,
        disk_resolution: int = 20,
        elevation_scale: float = 1,
        coverage: float = 1,
        extruded: bool = True,
        filled: bool = True,
        stroked: bool = False,
        wireframe: bool = False,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add a column layer using deck.gl."""
        layer_id = name or f"column-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addColumnLayer",
            id=layer_id,
            data=processed_data,
            getPosition=get_position,
            getFillColor=get_fill_color or [255, 140, 0, 200],
            getLineColor=get_line_color or [0, 0, 0, 255],
            getElevation=get_elevation,
            radius=radius,
            diskResolution=disk_resolution,
            elevationScale=elevation_scale,
            coverage=coverage,
            extruded=extruded,
            filled=filled,
            stroked=stroked,
            wireframe=wireframe,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {**self._layers, layer_id: {"id": layer_id, "type": "column"}}
        self._add_to_layer_dict(layer_id, "Deck.gl")

    def add_bitmap_layer(
        self,
        image: str,
        bounds: List[float],
        name: Optional[str] = None,
        opacity: float = 1.0,
        visible: bool = True,
        pickable: bool = False,
        desaturate: float = 0,
        transparent_color: Optional[List[int]] = None,
        tint_color: Optional[List[int]] = None,
        **kwargs,
    ) -> None:
        """Add a bitmap layer using deck.gl."""
        layer_id = name or f"bitmap-{len(self._layers)}"

        self.call_js_method(
            "addBitmapLayer",
            id=layer_id,
            image=image,
            bounds=bounds,
            opacity=opacity,
            visible=visible,
            pickable=pickable,
            desaturate=desaturate,
            transparentColor=transparent_color or [0, 0, 0, 0],
            tintColor=tint_color or [255, 255, 255],
            **kwargs,
        )

        self._layers = {**self._layers, layer_id: {"id": layer_id, "type": "bitmap"}}
        self._add_to_layer_dict(layer_id, "Deck.gl")

    def add_solid_polygon_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_polygon: Union[str, Any] = "polygon",
        get_fill_color: Optional[Union[List[int], str]] = None,
        get_line_color: Optional[Union[List[int], str]] = None,
        get_elevation: Union[float, str] = 0,
        filled: bool = True,
        extruded: bool = False,
        wireframe: bool = False,
        elevation_scale: float = 1,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add a solid polygon layer using deck.gl."""
        layer_id = name or f"solidpolygon-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addSolidPolygonLayer",
            id=layer_id,
            data=processed_data,
            getPolygon=get_polygon,
            getFillColor=get_fill_color or [51, 136, 255, 128],
            getLineColor=get_line_color or [0, 0, 0, 255],
            getElevation=get_elevation,
            filled=filled,
            extruded=extruded,
            wireframe=wireframe,
            elevationScale=elevation_scale,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {"id": layer_id, "type": "solidpolygon"},
        }
        self._add_to_layer_dict(layer_id, "Deck.gl")

    def add_grid_cell_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_position: Union[str, Any] = "coordinates",
        get_color: Optional[Union[List[int], str]] = None,
        get_elevation: Union[float, str] = 1000,
        cell_size: float = 200,
        coverage: float = 1,
        elevation_scale: float = 1,
        extruded: bool = True,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add a grid cell layer using deck.gl."""
        layer_id = name or f"gridcell-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addGridCellLayer",
            id=layer_id,
            data=processed_data,
            getPosition=get_position,
            getColor=get_color or [255, 140, 0, 200],
            getElevation=get_elevation,
            cellSize=cell_size,
            coverage=coverage,
            elevationScale=elevation_scale,
            extruded=extruded,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {"id": layer_id, "type": "gridcell"},
        }
        self._add_to_layer_dict(layer_id, "Deck.gl")

    # -------------------------------------------------------------------------
    # LiDAR Layers (maplibre-gl-lidar)
    # -------------------------------------------------------------------------

    def add_lidar_control(
        self,
        position: str = "top-right",
        collapsed: bool = True,
        title: str = "LiDAR Viewer",
        point_size: float = 2,
        opacity: float = 1.0,
        color_scheme: str = "elevation",
        use_percentile: bool = True,
        point_budget: int = 1000000,
        pickable: bool = False,
        auto_zoom: bool = True,
        copc_loading_mode: Optional[str] = None,
        streaming_point_budget: int = 5000000,
        **kwargs,
    ) -> None:
        """Add an interactive LiDAR control panel.

        The LiDAR control provides a UI panel for loading, visualizing, and
        styling LiDAR point cloud files (LAS, LAZ, COPC formats).

        Args:
            position: Control position ('top-left', 'top-right', 'bottom-left', 'bottom-right').
            collapsed: Whether the panel starts collapsed.
            title: Title displayed on the panel.
            point_size: Point size in pixels.
            opacity: Layer opacity (0-1).
            color_scheme: Color scheme ('elevation', 'intensity', 'classification', 'rgb').
            use_percentile: Use 2-98% percentile for color scaling.
            point_budget: Maximum number of points to display.
            pickable: Enable hover/click interactions.
            auto_zoom: Auto-zoom to point cloud after loading.
            copc_loading_mode: COPC loading mode ('full' or 'dynamic').
            streaming_point_budget: Point budget for streaming mode.
            **kwargs: Additional control options.

        Example:
            >>> from anymap_ts import MapboxMap
            >>> m = MapboxMap(pitch=60)
            >>> m.add_lidar_control(color_scheme="classification", pickable=True)
        """
        self.call_js_method(
            "addLidarControl",
            position=position,
            collapsed=collapsed,
            title=title,
            pointSize=point_size,
            opacity=opacity,
            colorScheme=color_scheme,
            usePercentile=use_percentile,
            pointBudget=point_budget,
            pickable=pickable,
            autoZoom=auto_zoom,
            copcLoadingMode=copc_loading_mode,
            streamingPointBudget=streaming_point_budget,
            **kwargs,
        )
        self._controls = {
            **self._controls,
            "lidar-control": {"position": position, "collapsed": collapsed},
        }

    def add_lidar_layer(
        self,
        source: Union[str, Path],
        name: Optional[str] = None,
        color_scheme: str = "elevation",
        point_size: float = 2,
        opacity: float = 1.0,
        pickable: bool = True,
        auto_zoom: bool = True,
        streaming_mode: bool = True,
        point_budget: int = 1000000,
        **kwargs,
    ) -> None:
        """Load and display a LiDAR file from URL or local path.

        Supports LAS, LAZ, and COPC (Cloud-Optimized Point Cloud) formats.
        For local files, the file is read and sent as base64 to JavaScript.
        For URLs, the data is loaded directly via streaming when possible.

        Args:
            source: URL or local file path to the LiDAR file.
            name: Layer identifier. If None, auto-generated.
            color_scheme: Color scheme ('elevation', 'intensity', 'classification', 'rgb').
            point_size: Point size in pixels.
            opacity: Layer opacity (0-1).
            pickable: Enable hover/click interactions.
            auto_zoom: Auto-zoom to point cloud after loading.
            streaming_mode: Use streaming mode for large COPC files.
            point_budget: Maximum number of points to display.
            **kwargs: Additional layer options.

        Example:
            >>> from anymap_ts import MapboxMap
            >>> m = MapboxMap(center=[-123.07, 44.05], zoom=14, pitch=60)
            >>> m.add_lidar_layer(
            ...     source="https://s3.amazonaws.com/hobu-lidar/autzen-classified.copc.laz",
            ...     name="autzen",
            ...     color_scheme="classification",
            ... )
        """
        import base64

        layer_id = name or f"lidar-{len(self._layers)}"

        # Check if source is a local file
        source_path = Path(source) if isinstance(source, (str, Path)) else None
        is_local = source_path is not None and source_path.exists()

        if is_local:
            # Read local file and encode as base64
            with open(source_path, "rb") as f:
                file_data = f.read()
            source_b64 = base64.b64encode(file_data).decode("utf-8")

            self.call_js_method(
                "addLidarLayer",
                source=source_b64,
                name=layer_id,
                isBase64=True,
                filename=source_path.name,
                colorScheme=color_scheme,
                pointSize=point_size,
                opacity=opacity,
                pickable=pickable,
                autoZoom=auto_zoom,
                streamingMode=streaming_mode,
                pointBudget=point_budget,
                **kwargs,
            )
        else:
            # Load from URL
            self.call_js_method(
                "addLidarLayer",
                source=str(source),
                name=layer_id,
                isBase64=False,
                colorScheme=color_scheme,
                pointSize=point_size,
                opacity=opacity,
                pickable=pickable,
                autoZoom=auto_zoom,
                streamingMode=streaming_mode,
                pointBudget=point_budget,
                **kwargs,
            )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "lidar",
                "source": str(source),
            },
        }

    def remove_lidar_layer(self, layer_id: Optional[str] = None) -> None:
        """Remove a LiDAR layer.

        Args:
            layer_id: Layer identifier to remove. If None, removes all LiDAR layers.
        """
        if layer_id:
            if layer_id in self._layers:
                layers = dict(self._layers)
                del layers[layer_id]
                self._layers = layers
            self.call_js_method("removeLidarLayer", id=layer_id)
        else:
            # Remove all lidar layers
            layers = dict(self._layers)
            self._layers = {k: v for k, v in layers.items() if v.get("type") != "lidar"}
            self.call_js_method("removeLidarLayer")

    def set_lidar_color_scheme(self, color_scheme: str) -> None:
        """Set the LiDAR color scheme.

        Args:
            color_scheme: Color scheme ('elevation', 'intensity', 'classification', 'rgb').
        """
        self.call_js_method("setLidarColorScheme", colorScheme=color_scheme)

    def set_lidar_point_size(self, point_size: float) -> None:
        """Set the LiDAR point size.

        Args:
            point_size: Point size in pixels.
        """
        self.call_js_method("setLidarPointSize", pointSize=point_size)

    def set_lidar_opacity(self, opacity: float) -> None:
        """Set the LiDAR layer opacity.

        Args:
            opacity: Opacity value between 0 and 1.
        """
        self.call_js_method("setLidarOpacity", opacity=opacity)

    def _process_deck_data(self, data: Any) -> Any:
        """Process data for deck.gl layers.

        Handles GeoDataFrame, file paths, GeoJSON, and list of dicts.

        Args:
            data: Input data in various formats.

        Returns:
            Processed data suitable for deck.gl layers.
        """
        # Handle GeoDataFrame
        if hasattr(data, "__geo_interface__"):
            return data.__geo_interface__

        # Handle file paths
        if isinstance(data, (str, Path)):
            path = Path(data)
            if path.exists():
                try:
                    import geopandas as gpd

                    gdf = gpd.read_file(path)
                    return gdf.__geo_interface__
                except ImportError:
                    pass

        # Return as-is for lists, dicts, etc.
        return data

    # -------------------------------------------------------------------------
    # Terrain Methods (Mapbox-specific)
    # -------------------------------------------------------------------------

    def add_terrain(
        self, exaggeration: float = 1.0, source: str = "mapbox-dem"
    ) -> None:
        """Add 3D terrain to the map.

        Args:
            exaggeration: Terrain exaggeration factor.
            source: Terrain source ID.
        """
        self.call_js_method("addTerrain", source=source, exaggeration=exaggeration)

    def remove_terrain(self) -> None:
        """Remove 3D terrain from the map."""
        self.call_js_method("removeTerrain")

    def add_3d_terrain(
        self, exaggeration: float = 1.0, source: str = "mapbox-dem", **kwargs
    ) -> None:
        """Alias for add_terrain for MapLibre compatibility."""
        self.add_terrain(exaggeration=exaggeration, source=source)

    # -------------------------------------------------------------------------
    # Layer Management
    # -------------------------------------------------------------------------

    def add_layer(
        self,
        layer_id: str,
        layer_type: str,
        source: Union[str, Dict],
        paint: Optional[Dict] = None,
        layout: Optional[Dict] = None,
        before_id: Optional[str] = None,
        **kwargs,
    ) -> None:
        """Add a generic layer to the map.

        Args:
            layer_id: Unique layer identifier.
            layer_type: Mapbox layer type.
            source: Source ID or source configuration dict.
            paint: Paint properties.
            layout: Layout properties.
            before_id: ID of layer to insert before.
            **kwargs: Additional layer options.
        """
        layer_config = {
            "id": layer_id,
            "type": layer_type,
            "paint": paint or {},
            "layout": layout or {},
            **kwargs,
        }

        if isinstance(source, str):
            layer_config["source"] = source
        else:
            source_id = f"{layer_id}-source"
            self._sources = {**self._sources, source_id: source}
            self.call_js_method("addSource", source_id, **source)
            layer_config["source"] = source_id

        self._layers = {**self._layers, layer_id: layer_config}
        self.call_js_method("addLayer", beforeId=before_id, **layer_config)
        lt = layer_config.get("type", "")
        self._add_to_layer_dict(layer_id, "Raster" if lt == "raster" else "Vector")

    def remove_layer(self, layer_id: str) -> None:
        """Remove a layer from the map."""
        if layer_id in self._layers:
            layers = dict(self._layers)
            del layers[layer_id]
            self._layers = layers
        self._remove_from_layer_dict(layer_id)
        self.call_js_method("removeLayer", layer_id)

    def set_visibility(self, layer_id: str, visible: bool) -> None:
        """Set layer visibility.

        Args:
            layer_id: Layer identifier.
            visible: Whether layer should be visible.
        """
        self.call_js_method("setVisibility", layer_id, visible)

    def set_opacity(self, layer_id: str, opacity: float) -> None:
        """Set layer opacity."""
        self._validate_opacity(opacity)
        self.call_js_method("setOpacity", layer_id, opacity)

    def set_paint_property(self, layer_id: str, property_name: str, value: Any) -> None:
        """Set a paint property for a layer."""
        self.call_js_method("setPaintProperty", layer_id, property_name, value)

    def set_layout_property(
        self, layer_id: str, property_name: str, value: Any
    ) -> None:
        """Set a layout property for a layer."""
        self.call_js_method("setLayoutProperty", layer_id, property_name, value)

    def move_layer(self, layer_id: str, before_id: Optional[str] = None) -> None:
        """Move a layer in the layer stack."""
        self.call_js_method("moveLayer", layer_id, before_id)

    def get_layer(self, layer_id: str) -> Optional[Dict]:
        """Get layer configuration by ID."""
        return self._layers.get(layer_id)

    def get_layer_ids(self) -> List[str]:
        """Get list of all layer IDs."""
        return list(self._layers.keys())

    def add_popup(
        self,
        layer_id: str,
        properties: Optional[List[str]] = None,
        template: Optional[str] = None,
        **kwargs,
    ) -> None:
        """Add popup on click for a layer."""
        self.call_js_method(
            "addPopup",
            layerId=layer_id,
            properties=properties,
            template=template,
            **kwargs,
        )

    # -------------------------------------------------------------------------
    # Controls
    # -------------------------------------------------------------------------

    def add_control(
        self,
        control_type: str,
        position: str = "top-right",
        **kwargs,
    ) -> None:
        """Add a map control.

        Args:
            control_type: Type of control ('navigation', 'scale', 'fullscreen', etc.).
            position: Control position.
            **kwargs: Control-specific options.
        """
        self.call_js_method("addControl", control_type, position=position, **kwargs)
        self._controls = {
            **self._controls,
            control_type: {"type": control_type, "position": position, **kwargs},
        }

    def remove_control(self, control_type: str) -> None:
        """Remove a map control."""
        self.call_js_method("removeControl", control_type)
        if control_type in self._controls:
            controls = dict(self._controls)
            del controls[control_type]
            self._controls = controls

    def add_layer_control(
        self,
        layers: Optional[List[str]] = None,
        position: str = "top-right",
        collapsed: bool = True,
    ) -> None:
        """Add a layer visibility control."""
        if layers is None:
            layers = list(self._layers.keys())

        self.call_js_method(
            "addLayerControl",
            layers=layers,
            position=position,
            collapsed=collapsed,
        )
        self._controls = {
            **self._controls,
            "layer-control": {
                "layers": layers,
                "position": position,
                "collapsed": collapsed,
            },
        }

    def add_colorbar(
        self,
        colormap: str = "viridis",
        vmin: float = 0,
        vmax: float = 1,
        label: str = "",
        units: str = "",
        orientation: str = "horizontal",
        position: str = "bottom-right",
        bar_thickness: Optional[int] = None,
        bar_length: Optional[int] = None,
        ticks: Optional[Dict] = None,
        opacity: Optional[float] = None,
        colorbar_id: Optional[str] = None,
        **kwargs,
    ) -> None:
        """Add a continuous gradient colorbar to the map."""
        self._validate_position(position)

        cbar_id = (
            colorbar_id
            or f"colorbar-{len([k for k in self._controls.keys() if k.startswith('colorbar')])}"
        )

        js_kwargs: Dict[str, Any] = {
            "colormap": colormap,
            "vmin": vmin,
            "vmax": vmax,
            "label": label,
            "units": units,
            "orientation": orientation,
            "position": position,
            "colorbarId": cbar_id,
            **kwargs,
        }
        if bar_thickness is not None:
            js_kwargs["barThickness"] = bar_thickness
        if bar_length is not None:
            js_kwargs["barLength"] = bar_length
        if ticks is not None:
            js_kwargs["ticks"] = ticks
        if opacity is not None:
            js_kwargs["opacity"] = opacity

        self.call_js_method("addColorbar", **js_kwargs)

        self._controls = {
            **self._controls,
            cbar_id: {
                "type": "colorbar",
                "colormap": colormap,
                "vmin": vmin,
                "vmax": vmax,
                "label": label,
                "units": units,
                "orientation": orientation,
                "position": position,
            },
        }

    def remove_colorbar(self, colorbar_id: Optional[str] = None) -> None:
        """Remove a colorbar from the map."""
        if colorbar_id is None:
            cbar_keys = [k for k in self._controls.keys() if k.startswith("colorbar")]
            for key in cbar_keys:
                self.call_js_method("removeColorbar", colorbarId=key)
            self._controls = {
                k: v for k, v in self._controls.items() if not k.startswith("colorbar")
            }
        else:
            self.call_js_method("removeColorbar", colorbarId=colorbar_id)
            if colorbar_id in self._controls:
                controls = dict(self._controls)
                del controls[colorbar_id]
                self._controls = controls

    def update_colorbar(self, colorbar_id: Optional[str] = None, **kwargs) -> None:
        """Update an existing colorbar's properties."""
        if colorbar_id is None:
            cbar_keys = [k for k in self._controls.keys() if k.startswith("colorbar")]
            if not cbar_keys:
                raise ValueError("No colorbar found to update")
            colorbar_id = cbar_keys[0]

        if colorbar_id not in self._controls:
            raise ValueError(f"Colorbar '{colorbar_id}' not found")

        js_kwargs: Dict[str, Any] = {"colorbarId": colorbar_id}
        key_map = {"bar_thickness": "barThickness", "bar_length": "barLength"}
        for key, value in kwargs.items():
            js_key = key_map.get(key, key)
            js_kwargs[js_key] = value

        self.call_js_method("updateColorbar", **js_kwargs)

    def add_search_control(
        self,
        position: str = "top-left",
        placeholder: str = "Search places...",
        collapsed: bool = True,
        fly_to_zoom: int = 14,
        show_marker: bool = True,
        marker_color: str = "#4264fb",
        **kwargs,
    ) -> None:
        """Add a search/geocoder control."""
        self._validate_position(position)
        self.call_js_method(
            "addSearchControl",
            position=position,
            placeholder=placeholder,
            collapsed=collapsed,
            flyToZoom=fly_to_zoom,
            showMarker=show_marker,
            markerColor=marker_color,
            **kwargs,
        )
        self._controls = {
            **self._controls,
            "search-control": {
                "type": "search-control",
                "position": position,
                "collapsed": collapsed,
            },
        }

    def remove_search_control(self) -> None:
        """Remove the search/geocoder control."""
        self.call_js_method("removeSearchControl")
        if "search-control" in self._controls:
            controls = dict(self._controls)
            del controls["search-control"]
            self._controls = controls

    def add_measure_control(
        self,
        position: str = "top-right",
        collapsed: bool = True,
        default_mode: str = "distance",
        distance_unit: str = "kilometers",
        area_unit: str = "square-kilometers",
        line_color: str = "#3b82f6",
        fill_color: str = "rgba(59, 130, 246, 0.2)",
        **kwargs,
    ) -> None:
        """Add a measurement control."""
        self._validate_position(position)
        self.call_js_method(
            "addMeasureControl",
            position=position,
            collapsed=collapsed,
            defaultMode=default_mode,
            distanceUnit=distance_unit,
            areaUnit=area_unit,
            lineColor=line_color,
            fillColor=fill_color,
            **kwargs,
        )
        self._controls = {
            **self._controls,
            "measure-control": {
                "type": "measure-control",
                "position": position,
                "collapsed": collapsed,
            },
        }

    def remove_measure_control(self) -> None:
        """Remove the measurement control."""
        self.call_js_method("removeMeasureControl")
        if "measure-control" in self._controls:
            controls = dict(self._controls)
            del controls["measure-control"]
            self._controls = controls

    def add_print_control(
        self,
        position: str = "top-right",
        collapsed: bool = True,
        format: str = "png",
        filename: str = "map-export",
        include_north_arrow: bool = False,
        include_scale_bar: bool = False,
        **kwargs,
    ) -> None:
        """Add a print/export control."""
        self._validate_position(position)
        self.call_js_method(
            "addPrintControl",
            position=position,
            collapsed=collapsed,
            format=format,
            filename=filename,
            includeNorthArrow=include_north_arrow,
            includeScaleBar=include_scale_bar,
            **kwargs,
        )
        self._controls = {
            **self._controls,
            "print-control": {
                "type": "print-control",
                "position": position,
                "collapsed": collapsed,
            },
        }

    def remove_print_control(self) -> None:
        """Remove the print/export control."""
        self.call_js_method("removePrintControl")
        if "print-control" in self._controls:
            controls = dict(self._controls)
            del controls["print-control"]
            self._controls = controls

    def add_coordinates_control(
        self,
        position: str = "bottom-left",
        precision: int = 4,
    ) -> None:
        """Add a coordinates display control."""
        self.call_js_method(
            "addCoordinatesControl",
            position=position,
            precision=precision,
        )

    def remove_coordinates_control(self) -> None:
        """Remove the coordinates display control."""
        self.call_js_method("removeCoordinatesControl")

    def add_time_slider(
        self,
        layer_id: str,
        property: str,
        min_value: float = 0,
        max_value: float = 100,
        step: float = 1,
        position: str = "bottom-left",
        label: str = "Time",
        auto_play: bool = False,
        interval: int = 500,
    ) -> None:
        """Add a time slider to filter data by a temporal property."""
        self.call_js_method(
            "addTimeSlider",
            layerId=layer_id,
            property=property,
            min=min_value,
            max=max_value,
            step=step,
            position=position,
            label=label,
            autoPlay=auto_play,
            interval=interval,
        )

    def remove_time_slider(self) -> None:
        """Remove the time slider control."""
        self.call_js_method("removeTimeSlider")

    def add_opacity_slider(
        self,
        layer_id: str,
        position: str = "top-right",
        label: Optional[str] = None,
    ) -> None:
        """Add a UI slider to control layer opacity."""
        self.call_js_method(
            "addOpacitySlider",
            layerId=layer_id,
            position=position,
            label=label or layer_id,
        )

    def remove_opacity_slider(self, layer_id: str) -> None:
        """Remove the opacity slider for a layer."""
        self.call_js_method("removeOpacitySlider", layerId=layer_id)

    def add_style_switcher(
        self,
        styles: Dict[str, str],
        position: str = "top-right",
    ) -> None:
        """Add a dropdown to switch between map styles."""
        self.call_js_method(
            "addStyleSwitcher",
            styles=styles,
            position=position,
        )

    def remove_style_switcher(self) -> None:
        """Remove the style switcher control."""
        self.call_js_method("removeStyleSwitcher")

    def add_pmtiles_control(
        self,
        position: str = "top-right",
        collapsed: bool = True,
        default_url: Optional[str] = None,
        load_default_url: bool = False,
        default_opacity: float = 1.0,
        default_fill_color: str = "steelblue",
        default_line_color: str = "#333",
        default_pickable: bool = True,
        **kwargs,
    ) -> None:
        """Add a PMTiles layer control."""
        self.call_js_method(
            "addPMTilesControl",
            position=position,
            collapsed=collapsed,
            defaultUrl=default_url or "",
            loadDefaultUrl=load_default_url,
            defaultOpacity=default_opacity,
            defaultFillColor=default_fill_color,
            defaultLineColor=default_line_color,
            defaultPickable=default_pickable,
            **kwargs,
        )
        self._controls = {
            **self._controls,
            "pmtiles-control": {"position": position, "collapsed": collapsed},
        }

    def add_cog_control(
        self,
        position: str = "top-right",
        collapsed: bool = True,
        default_url: Optional[str] = None,
        load_default_url: bool = False,
        default_opacity: float = 1.0,
        default_colormap: str = "viridis",
        default_bands: str = "1",
        default_rescale_min: float = 0,
        default_rescale_max: float = 255,
        **kwargs,
    ) -> None:
        """Add a COG layer control."""
        self.call_js_method(
            "addCogControl",
            position=position,
            collapsed=collapsed,
            defaultUrl=default_url or "",
            loadDefaultUrl=load_default_url,
            defaultOpacity=default_opacity,
            defaultColormap=default_colormap,
            defaultBands=default_bands,
            defaultRescaleMin=default_rescale_min,
            defaultRescaleMax=default_rescale_max,
            **kwargs,
        )
        self._controls = {
            **self._controls,
            "cog-control": {"position": position, "collapsed": collapsed},
        }

    def add_zarr_control(
        self,
        position: str = "top-right",
        collapsed: bool = True,
        default_url: Optional[str] = None,
        load_default_url: bool = False,
        default_opacity: float = 1.0,
        default_variable: str = "",
        default_clim: Optional[Tuple[float, float]] = None,
        **kwargs,
    ) -> None:
        """Add a Zarr layer control."""
        self.call_js_method(
            "addZarrControl",
            position=position,
            collapsed=collapsed,
            defaultUrl=default_url or "",
            loadDefaultUrl=load_default_url,
            defaultOpacity=default_opacity,
            defaultVariable=default_variable,
            defaultClim=list(default_clim) if default_clim else [0, 1],
            **kwargs,
        )
        self._controls = {
            **self._controls,
            "zarr-control": {"position": position, "collapsed": collapsed},
        }

    def add_vector_control(
        self,
        position: str = "top-right",
        collapsed: bool = True,
        default_url: Optional[str] = None,
        load_default_url: bool = False,
        default_opacity: float = 1.0,
        default_fill_color: str = "#3388ff",
        default_stroke_color: str = "#3388ff",
        fit_bounds: bool = True,
        **kwargs,
    ) -> None:
        """Add a vector layer control."""
        self.call_js_method(
            "addVectorControl",
            position=position,
            collapsed=collapsed,
            defaultUrl=default_url or "",
            loadDefaultUrl=load_default_url,
            defaultOpacity=default_opacity,
            defaultFillColor=default_fill_color,
            defaultStrokeColor=default_stroke_color,
            fitBounds=fit_bounds,
            **kwargs,
        )
        self._controls = {
            **self._controls,
            "vector-control": {"position": position, "collapsed": collapsed},
        }

    def add_control_grid(
        self,
        position: str = "top-right",
        default_controls: Optional[List[str]] = None,
        exclude: Optional[List[str]] = None,
        rows: Optional[int] = None,
        columns: Optional[int] = None,
        collapsed: bool = True,
        collapsible: bool = True,
        title: str = "",
        show_row_column_controls: bool = True,
        gap: int = 2,
        basemap_style_url: Optional[str] = None,
        exclude_layers: Optional[List[str]] = None,
        **kwargs,
    ) -> None:
        """Add a ControlGrid with all default tools or a custom subset."""
        js_kwargs: Dict[str, Any] = {
            "position": position,
            "collapsed": collapsed,
            "collapsible": collapsible,
            "showRowColumnControls": show_row_column_controls,
            "gap": gap,
            **kwargs,
        }
        if default_controls is not None:
            js_kwargs["defaultControls"] = default_controls
        if exclude is not None:
            js_kwargs["exclude"] = exclude
        if rows is not None:
            js_kwargs["rows"] = rows
        if columns is not None:
            js_kwargs["columns"] = columns
        if title:
            js_kwargs["title"] = title
        if basemap_style_url is not None:
            js_kwargs["basemapStyleUrl"] = basemap_style_url
        if exclude_layers is not None:
            js_kwargs["excludeLayers"] = exclude_layers

        self.call_js_method("addControlGrid", **js_kwargs)
        self._controls = {
            **self._controls,
            "control-grid": {
                "position": position,
                "collapsed": collapsed,
                "collapsible": collapsible,
            },
        }

    def add_legend(
        self,
        title: str,
        labels: List[str],
        colors: List[str],
        position: str = "bottom-right",
        opacity: float = 1.0,
        legend_id: Optional[str] = None,
        **kwargs,
    ) -> None:
        """Add a floating legend control to the map."""
        if len(labels) != len(colors):
            raise ValueError("Number of labels must match number of colors")

        self._validate_position(position)

        for i, color in enumerate(colors):
            if not isinstance(color, str) or not color.startswith("#"):
                raise ValueError(
                    f"Color at index {i} must be a hex color string (e.g., '#ff0000')"
                )

        legend_id = (
            legend_id
            or f"legend-{len([k for k in self._controls.keys() if k.startswith('legend')])}"
        )

        legend_items = [
            {"label": label, "color": color} for label, color in zip(labels, colors)
        ]

        self.call_js_method(
            "addLegend",
            id=legend_id,
            title=title,
            items=legend_items,
            position=position,
            opacity=opacity,
            **kwargs,
        )

        self._controls = {
            **self._controls,
            legend_id: {
                "type": "legend",
                "title": title,
                "labels": labels,
                "colors": colors,
                "position": position,
                "opacity": opacity,
            },
        }

    def remove_legend(self, legend_id: Optional[str] = None) -> None:
        """Remove a legend control from the map."""
        if legend_id is None:
            legend_keys = [k for k in self._controls.keys() if k.startswith("legend")]
            for key in legend_keys:
                self.call_js_method("removeLegend", key)
            self._controls = {
                k: v for k, v in self._controls.items() if not k.startswith("legend")
            }
        else:
            self.call_js_method("removeLegend", legend_id)
            if legend_id in self._controls:
                controls = dict(self._controls)
                del controls[legend_id]
                self._controls = controls

    def update_legend(
        self,
        legend_id: str,
        title: Optional[str] = None,
        labels: Optional[List[str]] = None,
        colors: Optional[List[str]] = None,
        opacity: Optional[float] = None,
        **kwargs,
    ) -> None:
        """Update an existing legend's properties."""
        if legend_id not in self._controls:
            raise ValueError(f"Legend '{legend_id}' not found")

        update_params = {"id": legend_id}

        if title is not None:
            update_params["title"] = title
            self._controls[legend_id]["title"] = title

        if labels is not None and colors is not None:
            if len(labels) != len(colors):
                raise ValueError("Number of labels must match number of colors")

            legend_items = [
                {"label": label, "color": color} for label, color in zip(labels, colors)
            ]
            update_params["items"] = legend_items
            self._controls[legend_id]["labels"] = labels
            self._controls[legend_id]["colors"] = colors

        elif labels is not None or colors is not None:
            raise ValueError("Both labels and colors must be provided together")

        if opacity is not None:
            update_params["opacity"] = opacity
            self._controls[legend_id]["opacity"] = opacity

        update_params.update(kwargs)
        self.call_js_method("updateLegend", **update_params)

    def add_tooltip(
        self,
        layer_id: str,
        template: Optional[str] = None,
        properties: Optional[List[str]] = None,
    ) -> None:
        """Add a tooltip that shows on feature hover."""
        self.call_js_method(
            "addTooltip",
            layerId=layer_id,
            template=template or "",
            properties=properties,
        )

    def remove_tooltip(self, layer_id: str) -> None:
        """Remove tooltip from a layer."""
        self.call_js_method("removeTooltip", layerId=layer_id)

    def add_flatgeobuf(
        self,
        url: str,
        name: Optional[str] = None,
        layer_type: Optional[str] = None,
        paint: Optional[Dict] = None,
        fit_bounds: bool = True,
        **kwargs,
    ) -> None:
        """Add a FlatGeobuf layer from a URL."""
        layer_id = name or f"flatgeobuf-{len(self._layers)}"

        self.call_js_method(
            "addFlatGeobuf",
            url=url,
            name=layer_id,
            layerType=layer_type,
            paint=paint,
            fitBounds=fit_bounds,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "flatgeobuf",
                "url": url,
            },
        }
        self._add_to_layer_dict(layer_id, "Vector")

    def remove_flatgeobuf(self, name: str) -> None:
        """Remove a FlatGeobuf layer from the map."""
        if name in self._layers:
            layers = dict(self._layers)
            del layers[name]
            self._layers = layers
        self._remove_from_layer_dict(name)
        self.call_js_method("removeFlatGeobuf", name=name)

    def add_draw_control(
        self,
        position: str = "top-right",
        draw_modes: Optional[List[str]] = None,
        edit_modes: Optional[List[str]] = None,
        collapsed: bool = False,
        **kwargs,
    ) -> None:
        """Add a drawing control."""
        if draw_modes is None:
            draw_modes = ["polygon", "line", "rectangle", "circle", "marker"]
        if edit_modes is None:
            edit_modes = ["select", "drag", "change", "rotate", "delete"]

        self.call_js_method(
            "addDrawControl",
            position=position,
            drawModes=draw_modes,
            editModes=edit_modes,
            collapsed=collapsed,
            **kwargs,
        )
        self._controls = {
            **self._controls,
            "draw-control": {
                "position": position,
                "drawModes": draw_modes,
                "editModes": edit_modes,
            },
        }

    def get_draw_data(self) -> Dict:
        """Get the current drawn features as GeoJSON."""
        self.call_js_method("getDrawData")
        import time

        time.sleep(0.1)
        return self._draw_data or {"type": "FeatureCollection", "features": []}

    @property
    def draw_data(self) -> Dict:
        """Property to access current draw data."""
        return self._draw_data or {"type": "FeatureCollection", "features": []}

    def load_draw_data(self, geojson: Dict) -> None:
        """Load GeoJSON features into the drawing layer."""
        self._draw_data = geojson
        self.call_js_method("loadDrawData", geojson)

    def clear_draw_data(self) -> None:
        """Clear all drawn features."""
        self._draw_data = {"type": "FeatureCollection", "features": []}
        self.call_js_method("clearDrawData")

    def save_draw_data(
        self,
        filepath: Union[str, Path],
        driver: Optional[str] = None,
    ) -> None:
        """Save drawn features to a file."""
        try:
            import geopandas as gpd
        except ImportError:
            raise ImportError(
                "geopandas is required to save draw data. "
                "Install with: pip install anymap-ts[vector]"
            )

        data = self.get_draw_data()
        if not data.get("features"):
            print("No features to save")
            return

        gdf = gpd.GeoDataFrame.from_features(data["features"])
        filepath = Path(filepath)

        if driver is None:
            ext = filepath.suffix.lower()
            driver_map = {
                ".geojson": "GeoJSON",
                ".json": "GeoJSON",
                ".shp": "ESRI Shapefile",
                ".gpkg": "GPKG",
            }
            driver = driver_map.get(ext, "GeoJSON")

        gdf.to_file(filepath, driver=driver)

    def add_cluster_layer(
        self,
        data: Any,
        cluster_radius: int = 50,
        cluster_max_zoom: int = 14,
        cluster_colors: Optional[List[str]] = None,
        cluster_steps: Optional[List[int]] = None,
        cluster_min_radius: int = 15,
        cluster_max_radius: int = 30,
        unclustered_color: str = "#11b4da",
        unclustered_radius: int = 8,
        show_cluster_count: bool = True,
        name: Optional[str] = None,
        zoom_on_click: bool = True,
        fit_bounds: bool = True,
        **kwargs,
    ) -> str:
        """Add a clustered point layer."""
        layer_id = name or f"cluster-{len(self._layers)}"

        if cluster_colors is None:
            cluster_colors = ["#51bbd6", "#f1f075", "#f28cb1"]
        if cluster_steps is None:
            cluster_steps = [100, 750]

        if len(cluster_steps) != len(cluster_colors) - 1:
            raise ValueError(
                f"cluster_steps must have {len(cluster_colors) - 1} values "
                f"(one less than cluster_colors), got {len(cluster_steps)}"
            )

        geojson = to_geojson(data)

        if geojson.get("type") == "url":
            url = geojson["url"]
            geojson = fetch_geojson(url)

        bounds = get_bounds(geojson) if fit_bounds else None

        self.call_js_method(
            "addClusterLayer",
            data=geojson,
            name=layer_id,
            clusterRadius=cluster_radius,
            clusterMaxZoom=cluster_max_zoom,
            clusterColors=cluster_colors,
            clusterSteps=cluster_steps,
            clusterMinRadius=cluster_min_radius,
            clusterMaxRadius=cluster_max_radius,
            unclusteredColor=unclustered_color,
            unclusteredRadius=unclustered_radius,
            showClusterCount=show_cluster_count,
            zoomOnClick=zoom_on_click,
            fitBounds=fit_bounds,
            bounds=bounds,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "cluster",
                "source": f"{layer_id}-source",
            },
        }
        self._add_to_layer_dict(layer_id, "Vector")
        return layer_id

    def remove_cluster_layer(self, layer_id: str) -> None:
        """Remove a cluster layer."""
        self._remove_layer_internal(layer_id, "removeClusterLayer")

    def add_choropleth(
        self,
        data: Any,
        column: str,
        cmap: str = "viridis",
        classification: str = "quantile",
        k: int = 5,
        breaks: Optional[List[float]] = None,
        fill_opacity: float = 0.7,
        line_color: str = "#000000",
        line_width: float = 1,
        legend: bool = True,
        legend_title: Optional[str] = None,
        hover: bool = True,
        layer_id: Optional[str] = None,
        fit_bounds: bool = True,
        **kwargs,
    ) -> None:
        """Add a choropleth (thematic) map layer."""
        from .utils import (
            get_choropleth_colors,
            compute_breaks,
            build_step_expression,
        )

        layer_name = layer_id or f"choropleth-{len(self._layers)}"

        geojson = to_geojson(data)

        if geojson.get("type") == "url":
            url = geojson["url"]
            geojson = fetch_geojson(url)

        features = geojson.get("features", [])
        values = []
        for feature in features:
            props = feature.get("properties", {})
            val = props.get(column)
            if val is not None:
                try:
                    values.append(float(val))
                except (TypeError, ValueError):
                    pass

        if not values:
            raise ValueError(f"No valid numeric values found for column '{column}'")

        computed_breaks = compute_breaks(values, classification, k, breaks)

        colors = get_choropleth_colors(cmap, k)

        step_expr = build_step_expression(column, computed_breaks, colors)

        bounds = get_bounds(geojson) if fit_bounds else None

        self.call_js_method(
            "addChoropleth",
            data=geojson,
            name=layer_name,
            column=column,
            stepExpression=step_expr,
            fillOpacity=fill_opacity,
            lineColor=line_color,
            lineWidth=line_width,
            hover=hover,
            fitBounds=fit_bounds,
            bounds=bounds,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_name: {
                "id": layer_name,
                "type": "choropleth",
                "source": f"{layer_name}-source",
                "column": column,
            },
        }
        self._add_to_layer_dict(layer_name, "Vector")

        if legend:
            title = legend_title or column
            labels = []
            for i in range(len(computed_breaks) - 1):
                low = computed_breaks[i]
                high = computed_breaks[i + 1]
                labels.append(f"{low:.1f} - {high:.1f}")

            self.add_legend(
                title=title,
                labels=labels,
                colors=colors,
                position="bottom-right",
            )

    def add_3d_buildings(
        self,
        source: str = "openmaptiles",
        min_zoom: float = 14,
        fill_extrusion_color: str = "#aaa",
        fill_extrusion_opacity: float = 0.6,
        height_property: str = "render_height",
        base_property: str = "render_min_height",
        layer_id: Optional[str] = None,
        **kwargs,
    ) -> None:
        """Add 3D building extrusions from vector tiles."""
        layer_name = layer_id or "3d-buildings"

        self.call_js_method(
            "add3DBuildings",
            source=source,
            minZoom=min_zoom,
            fillExtrusionColor=fill_extrusion_color,
            fillExtrusionOpacity=fill_extrusion_opacity,
            heightProperty=height_property,
            baseProperty=base_property,
            layerId=layer_name,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_name: {
                "id": layer_name,
                "type": "fill-extrusion",
            },
        }
        self._add_to_layer_dict(layer_name, "Vector")

    def animate_along_route(
        self,
        route: Any,
        duration: int = 10000,
        loop: bool = True,
        marker_color: str = "#3388ff",
        marker_size: float = 1.0,
        show_trail: bool = False,
        trail_color: str = "#3388ff",
        trail_width: float = 3,
        animation_id: Optional[str] = None,
        **kwargs,
    ) -> str:
        """Animate a marker along a route."""
        anim_id = animation_id or f"animation-{len(self._layers)}"

        if isinstance(route, list) and len(route) > 0:
            if isinstance(route[0], (list, tuple)):
                coordinates = route
            else:
                raise ValueError("Route list must contain coordinate pairs")
        elif isinstance(route, dict):
            if route.get("type") == "LineString":
                coordinates = route.get("coordinates", [])
            elif route.get("type") == "Feature":
                geometry = route.get("geometry", {})
                if geometry.get("type") == "LineString":
                    coordinates = geometry.get("coordinates", [])
                else:
                    raise ValueError("Feature geometry must be LineString")
            elif route.get("type") == "FeatureCollection":
                features = route.get("features", [])
                if (
                    features
                    and features[0].get("geometry", {}).get("type") == "LineString"
                ):
                    coordinates = features[0]["geometry"]["coordinates"]
                else:
                    raise ValueError(
                        "FeatureCollection must contain LineString features"
                    )
            else:
                raise ValueError(
                    "GeoJSON must be LineString, Feature, or FeatureCollection"
                )
        else:
            geojson = to_geojson(route)
            if geojson.get("type") == "url":
                geojson = fetch_geojson(geojson["url"])
            if geojson.get("type") == "FeatureCollection":
                features = geojson.get("features", [])
                if features:
                    coordinates = features[0].get("geometry", {}).get("coordinates", [])
                else:
                    raise ValueError("No features found in data")
            elif geojson.get("type") == "Feature":
                coordinates = geojson.get("geometry", {}).get("coordinates", [])
            else:
                coordinates = geojson.get("coordinates", [])

        if len(coordinates) < 2:
            raise ValueError("Route must have at least 2 points")

        self.call_js_method(
            "animateAlongRoute",
            id=anim_id,
            coordinates=coordinates,
            duration=duration,
            loop=loop,
            markerColor=marker_color,
            markerSize=marker_size,
            showTrail=show_trail,
            trailColor=trail_color,
            trailWidth=trail_width,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            anim_id: {
                "id": anim_id,
                "type": "animation",
            },
        }
        return anim_id

    def stop_animation(self, animation_id: str) -> None:
        """Stop a running animation."""
        self.call_js_method("stopAnimation", animation_id)
        if animation_id in self._layers:
            layers = dict(self._layers)
            del layers[animation_id]
            self._layers = layers

    def pause_animation(self, animation_id: str) -> None:
        """Pause a running animation."""
        self.call_js_method("pauseAnimation", animation_id)

    def resume_animation(self, animation_id: str) -> None:
        """Resume a paused animation."""
        self.call_js_method("resumeAnimation", animation_id)

    def set_animation_speed(self, animation_id: str, speed: float) -> None:
        """Set animation speed multiplier."""
        self.call_js_method("setAnimationSpeed", animation_id, speed)

    def add_hover_effect(
        self,
        layer_id: str,
        highlight_color: Optional[str] = None,
        highlight_opacity: Optional[float] = None,
        highlight_outline_width: float = 2,
        **kwargs,
    ) -> None:
        """Add hover highlight effect to an existing layer."""
        self.call_js_method(
            "addHoverEffect",
            layerId=layer_id,
            highlightColor=highlight_color,
            highlightOpacity=highlight_opacity,
            highlightOutlineWidth=highlight_outline_width,
            **kwargs,
        )

    def set_fog(
        self,
        color: Optional[str] = None,
        high_color: Optional[str] = None,
        low_color: Optional[str] = None,
        horizon_blend: Optional[float] = None,
        range: Optional[List[float]] = None,
        **kwargs,
    ) -> None:
        """Set fog atmospheric effect (Mapbox uses map.setFog() API)."""
        self.call_js_method(
            "setFog",
            color=color,
            highColor=high_color,
            lowColor=low_color,
            horizonBlend=horizon_blend,
            range=range,
            **kwargs,
        )

    def remove_fog(self) -> None:
        """Remove fog atmospheric effects from the map."""
        self.call_js_method("removeFog")

    def add_image_layer(
        self,
        url: str,
        coordinates: List[List[float]],
        name: Optional[str] = None,
        opacity: float = 1.0,
        **kwargs,
    ) -> None:
        """Add a georeferenced image overlay."""
        self._validate_opacity(opacity)
        layer_id = name or f"image-{len(self._layers)}"

        if len(coordinates) != 4:
            raise ValueError(
                "coordinates must have exactly 4 corner points "
                "[top-left, top-right, bottom-right, bottom-left]"
            )

        self.call_js_method(
            "addImageLayer",
            id=layer_id,
            url=url,
            coordinates=coordinates,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "image",
                "url": url,
                "coordinates": coordinates,
            },
        }
        self._add_to_layer_dict(layer_id, "Raster")

    def add_video_layer(
        self,
        urls: List[str],
        coordinates: List[List[float]],
        name: Optional[str] = None,
        opacity: float = 1.0,
        **kwargs,
    ) -> None:
        """Add a georeferenced video overlay on the map."""
        self._validate_opacity(opacity)
        layer_id = name or f"video-{len(self._layers)}"

        if len(coordinates) != 4:
            raise ValueError(
                "coordinates must have exactly 4 corner points "
                "[top-left, top-right, bottom-right, bottom-left]"
            )

        self.call_js_method(
            "addVideoLayer",
            id=layer_id,
            urls=urls,
            coordinates=coordinates,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "video",
                "source": f"{layer_id}-source",
            },
        }
        self._add_to_layer_dict(layer_id, "Raster")

    def remove_video_layer(self, name: str) -> None:
        """Remove a video layer from the map."""
        if name in self._layers:
            layers = dict(self._layers)
            del layers[name]
            self._layers = layers
        self._remove_from_layer_dict(name)
        self.call_js_method("removeVideoLayer", id=name)

    def play_video(self, name: str) -> None:
        """Start playing a video layer."""
        self.call_js_method("playVideo", id=name)

    def pause_video(self, name: str) -> None:
        """Pause a video layer."""
        self.call_js_method("pauseVideo", id=name)

    def seek_video(self, name: str, time: float) -> None:
        """Seek to a specific time in a video layer."""
        self.call_js_method("seekVideo", id=name, time=time)

    def add_split_map(
        self,
        left_layer: str,
        right_layer: str,
        position: int = 50,
    ) -> None:
        """Add a split map comparison view with a draggable divider."""
        if not 0 <= position <= 100:
            raise ValueError(f"position must be between 0 and 100, got {position}")

        self.call_js_method(
            "addSplitMap",
            leftLayer=left_layer,
            rightLayer=right_layer,
            position=position,
        )

    def remove_split_map(self) -> None:
        """Remove the split map comparison view."""
        self.call_js_method("removeSplitMap")

    def set_projection(self, projection: str = "mercator") -> None:
        """Set the map projection (Mapbox supports 'globe' and 'mercator')."""
        self.call_js_method("setProjection", projection=projection)

    def update_geojson_source(self, source_id: str, data: Any) -> None:
        """Update the data of an existing GeoJSON source in place."""
        processed_data = self._process_deck_data(data)
        self.call_js_method(
            "updateGeoJSONSource",
            sourceId=source_id,
            data=processed_data,
        )

    def add_image(self, name: str, url: str) -> None:
        """Load a custom icon image for use in symbol layers."""
        self.call_js_method("addMapImage", name=name, url=url)

    def add_swipe_map(self, left_layer: str, right_layer: str) -> None:
        """Add a drag-to-compare swipe control for two layers."""
        self.call_js_method(
            "addSwipeMap",
            leftLayer=left_layer,
            rightLayer=right_layer,
        )

    def remove_swipe_map(self) -> None:
        """Remove the swipe map comparison control."""
        self.call_js_method("removeSwipeMap")

    def set_filter(
        self,
        layer_id: str,
        filter_expression: Optional[List] = None,
    ) -> None:
        """Set or clear a filter on a map layer."""
        self.call_js_method(
            "setFilter",
            layerId=layer_id,
            filter=filter_expression,
        )

    def query_rendered_features(
        self,
        geometry: Optional[Any] = None,
        layers: Optional[List[str]] = None,
        filter_expression: Optional[List] = None,
    ) -> Dict:
        """Query features currently rendered on the map."""
        kwargs: Dict[str, Any] = {}
        if geometry is not None:
            kwargs["geometry"] = geometry
        if layers is not None:
            kwargs["layers"] = layers
        if filter_expression is not None:
            kwargs["filter"] = filter_expression

        self.call_js_method("queryRenderedFeatures", **kwargs)
        return self._queried_features

    def query_source_features(
        self,
        source_id: str,
        source_layer: Optional[str] = None,
        filter_expression: Optional[List] = None,
    ) -> Dict:
        """Query features from a source."""
        kwargs: Dict[str, Any] = {"sourceId": source_id}
        if source_layer is not None:
            kwargs["sourceLayer"] = source_layer
        if filter_expression is not None:
            kwargs["filter"] = filter_expression

        self.call_js_method("querySourceFeatures", **kwargs)
        return self._queried_features

    @property
    def queried_features(self) -> Dict:
        """Get the most recent query results."""
        return self._queried_features

    def get_visible_features(
        self,
        layers: Optional[List[str]] = None,
    ) -> Optional[Dict]:
        """Get all features currently visible in the viewport."""
        if layers is not None:
            self.call_js_method("getVisibleFeatures", layers=layers)
        features = self._queried_features
        if features and "data" in features:
            return features["data"]
        return None

    def to_geojson(self, layer_id: Optional[str] = None) -> Optional[Dict]:
        """Get layer data as GeoJSON."""
        if layer_id:
            self.call_js_method("getLayerData", sourceId=layer_id)
        features = self._queried_features
        if features and "data" in features:
            return features["data"]
        return None

    def to_geopandas(self, layer_id: Optional[str] = None) -> Any:
        """Get layer data as a GeoDataFrame."""
        geojson = self.to_geojson(layer_id)
        if geojson is None:
            return None
        try:
            import geopandas as gpd

            return gpd.GeoDataFrame.from_features(geojson.get("features", []))
        except ImportError:
            raise ImportError("geopandas is required for to_geopandas()")

    # -------------------------------------------------------------------------
    # Markers
    # -------------------------------------------------------------------------

    def add_marker(
        self,
        lng: float,
        lat: float,
        popup: Optional[str] = None,
        tooltip: Optional[str] = None,
        color: str = "#3388ff",
        draggable: bool = False,
        scale: float = 1.0,
        popup_max_width: str = "240px",
        tooltip_max_width: str = "240px",
        name: Optional[str] = None,
        **kwargs,
    ) -> str:
        """Add a single marker to the map."""
        marker_id = name or f"marker-{len(self._layers)}"

        self.call_js_method(
            "addMarker",
            lng,
            lat,
            id=marker_id,
            popup=popup,
            tooltip=tooltip,
            color=color,
            draggable=draggable,
            scale=scale,
            popupMaxWidth=popup_max_width,
            tooltipMaxWidth=tooltip_max_width,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            marker_id: {
                "id": marker_id,
                "type": "marker",
                "lngLat": [lng, lat],
            },
        }
        self._add_to_layer_dict(marker_id, "Markers")
        return marker_id

    def add_markers(
        self,
        data: Any,
        lng_column: Optional[str] = None,
        lat_column: Optional[str] = None,
        popup_column: Optional[str] = None,
        tooltip_column: Optional[str] = None,
        color: str = "#3388ff",
        scale: float = 1.0,
        popup_max_width: str = "240px",
        tooltip_max_width: str = "240px",
        draggable: bool = False,
        name: Optional[str] = None,
        **kwargs,
    ) -> str:
        """Add multiple markers from data."""
        layer_id = name or f"markers-{len(self._layers)}"
        markers = []

        if hasattr(data, "geometry"):
            for _, row in data.iterrows():
                geom = row.geometry
                if geom.geom_type == "Point":
                    marker = {"lngLat": [geom.x, geom.y]}
                    if popup_column and popup_column in row:
                        marker["popup"] = str(row[popup_column])
                    if tooltip_column and tooltip_column in row:
                        marker["tooltip"] = str(row[tooltip_column])
                    markers.append(marker)
        elif isinstance(data, dict) and data.get("type") == "FeatureCollection":
            for feature in data.get("features", []):
                geom = feature.get("geometry", {})
                if geom.get("type") == "Point":
                    coords = geom.get("coordinates", [])
                    marker = {"lngLat": coords[:2]}
                    props = feature.get("properties", {})
                    if popup_column and popup_column in props:
                        marker["popup"] = str(props[popup_column])
                    if tooltip_column and tooltip_column in props:
                        marker["tooltip"] = str(props[tooltip_column])
                    markers.append(marker)
        elif isinstance(data, list):
            lng_keys = ["lng", "lon", "longitude", "x"]
            lat_keys = ["lat", "latitude", "y"]

            for item in data:
                if not isinstance(item, dict):
                    continue

                lng_val = None
                lat_val = None

                if lng_column and lng_column in item:
                    lng_val = item[lng_column]
                else:
                    for key in lng_keys:
                        if key in item:
                            lng_val = item[key]
                            break

                if lat_column and lat_column in item:
                    lat_val = item[lat_column]
                else:
                    for key in lat_keys:
                        if key in item:
                            lat_val = item[key]
                            break

                if lng_val is not None and lat_val is not None:
                    marker = {"lngLat": [float(lng_val), float(lat_val)]}
                    if popup_column and popup_column in item:
                        marker["popup"] = str(item[popup_column])
                    if tooltip_column and tooltip_column in item:
                        marker["tooltip"] = str(item[tooltip_column])
                    markers.append(marker)

        if not markers:
            raise ValueError("No valid point data found in input")

        self.call_js_method(
            "addMarkers",
            id=layer_id,
            markers=markers,
            color=color,
            scale=scale,
            popupMaxWidth=popup_max_width,
            tooltipMaxWidth=tooltip_max_width,
            draggable=draggable,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "markers",
                "count": len(markers),
            },
        }
        self._add_to_layer_dict(layer_id, "Markers")
        return layer_id

    def remove_marker(self, marker_id: str) -> None:
        """Remove a marker from the map."""
        self._remove_layer_internal(marker_id, "removeMarker")

    # -------------------------------------------------------------------------
    # HTML Export
    # -------------------------------------------------------------------------

    def _generate_html_template(self) -> str:
        """Generate standalone HTML for the map."""
        template_path = Path(__file__).parent / "templates" / "mapbox.html"

        if template_path.exists():
            template = template_path.read_text(encoding="utf-8")
        else:
            template = self._get_default_template()

        # Serialize state
        state = {
            "center": self.center,
            "zoom": self.zoom,
            "style": self.style,
            "bearing": self.bearing,
            "pitch": self.pitch,
            "width": self.width,
            "height": self.height,
            "layers": self._layers,
            "sources": self._sources,
            "controls": self._controls,
            "js_calls": self._js_calls,
            "access_token": self.access_token,
        }

        template = template.replace("{{state}}", json.dumps(state, indent=2))
        return template

    def _get_default_template(self) -> str:
        """Get default HTML template."""
        return """<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>{{title}}</title>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://api.mapbox.com/mapbox-gl-js/v3.0.0/mapbox-gl.js"></script>
    <link href="https://api.mapbox.com/mapbox-gl-js/v3.0.0/mapbox-gl.css" rel="stylesheet" />
    <style>
        body { margin: 0; padding: 0; }
        #map { position: absolute; top: 0; bottom: 0; width: 100%; }
    </style>
</head>
<body>
    <div id="map"></div>
    <script>
        const state = {{state}};

        mapboxgl.accessToken = state.access_token;

        const map = new mapboxgl.Map({
            container: 'map',
            style: state.style,
            center: state.center,
            zoom: state.zoom,
            bearing: state.bearing || 0,
            pitch: state.pitch || 0
        });

        map.on('load', function() {
            // Replay JS calls
            for (const call of state.js_calls || []) {
                try {
                    executeMethod(call.method, call.args, call.kwargs);
                } catch (e) {
                    console.error('Error executing', call.method, e);
                }
            }
        });

        function executeMethod(method, args, kwargs) {
            switch (method) {
                case 'addBasemap':
                    const url = args[0];
                    const name = kwargs.name || 'basemap';
                    const sourceId = 'basemap-' + name;
                    if (!map.getSource(sourceId)) {
                        map.addSource(sourceId, {
                            type: 'raster',
                            tiles: [url],
                            tileSize: 256,
                            attribution: kwargs.attribution || ''
                        });
                    }
                    if (!map.getLayer(sourceId)) {
                        map.addLayer({
                            id: sourceId,
                            type: 'raster',
                            source: sourceId
                        });
                    }
                    break;

                case 'addGeoJSON':
                    const layerName = kwargs.name;
                    const sourceIdGeo = layerName + '-source';
                    if (!map.getSource(sourceIdGeo)) {
                        map.addSource(sourceIdGeo, {
                            type: 'geojson',
                            data: kwargs.data
                        });
                    }
                    if (!map.getLayer(layerName)) {
                        map.addLayer({
                            id: layerName,
                            type: kwargs.layerType || 'circle',
                            source: sourceIdGeo,
                            paint: kwargs.paint || {}
                        });
                    }
                    if (kwargs.fitBounds && kwargs.bounds) {
                        map.fitBounds([
                            [kwargs.bounds[0], kwargs.bounds[1]],
                            [kwargs.bounds[2], kwargs.bounds[3]]
                        ], { padding: 50 });
                    }
                    break;

                case 'addTileLayer':
                    const tileUrl = args[0];
                    const tileName = kwargs.name;
                    const tileSourceId = tileName + '-source';
                    if (!map.getSource(tileSourceId)) {
                        map.addSource(tileSourceId, {
                            type: 'raster',
                            tiles: [tileUrl],
                            tileSize: 256,
                            attribution: kwargs.attribution || ''
                        });
                    }
                    if (!map.getLayer(tileName)) {
                        map.addLayer({
                            id: tileName,
                            type: 'raster',
                            source: tileSourceId
                        });
                    }
                    break;

                case 'addControl':
                    const controlType = args[0];
                    const position = kwargs.position || 'top-right';
                    let control;
                    switch (controlType) {
                        case 'navigation':
                            control = new mapboxgl.NavigationControl();
                            break;
                        case 'scale':
                            control = new mapboxgl.ScaleControl();
                            break;
                        case 'fullscreen':
                            control = new mapboxgl.FullscreenControl();
                            break;
                    }
                    if (control) {
                        map.addControl(control, position);
                    }
                    break;

                case 'addTerrain':
                    const terrainSource = kwargs.source || 'mapbox-dem';
                    if (!map.getSource(terrainSource)) {
                        map.addSource(terrainSource, {
                            type: 'raster-dem',
                            url: 'mapbox://mapbox.mapbox-terrain-dem-v1',
                            tileSize: 512,
                            maxzoom: 14
                        });
                    }
                    map.setTerrain({ source: terrainSource, exaggeration: kwargs.exaggeration || 1 });
                    break;

                case 'removeTerrain':
                    map.setTerrain(null);
                    break;

                case 'flyTo':
                    map.flyTo({
                        center: [args[0], args[1]],
                        zoom: kwargs.zoom,
                        duration: kwargs.duration || 2000
                    });
                    break;

                case 'fitBounds':
                    const bounds = args[0];
                    map.fitBounds([
                        [bounds[0], bounds[1]],
                        [bounds[2], bounds[3]]
                    ], {
                        padding: kwargs.padding || 50,
                        duration: kwargs.duration || 1000
                    });
                    break;

                case 'addMarker':
                    new mapboxgl.Marker({ color: kwargs.color || '#3388ff' })
                        .setLngLat([args[0], args[1]])
                        .addTo(map);
                    break;

                default:
                    console.log('Unknown method:', method);
            }
        }
    </script>
</body>
</html>"""

draw_data: Dict property readonly

Property to access current draw data.

queried_features: Dict property readonly

Get the most recent query results.

__init__(self, center=(0.0, 0.0), zoom=2.0, width='100%', height='600px', style='mapbox://styles/mapbox/streets-v12', bearing=0.0, pitch=0.0, max_pitch=85.0, access_token=None, controls=None, **kwargs) special

Initialize a Mapbox map.

Parameters:

Name Type Description Default
center Tuple[float, float]

Map center as (longitude, latitude).

(0.0, 0.0)
zoom float

Initial zoom level.

2.0
width str

Map width as CSS string.

'100%'
height str

Map height as CSS string.

'600px'
style str

Mapbox style URL (e.g., "mapbox://styles/mapbox/streets-v12").

'mapbox://styles/mapbox/streets-v12'
bearing float

Map bearing in degrees.

0.0
pitch float

Map pitch in degrees.

0.0
max_pitch float

Maximum pitch angle in degrees (default: 85).

85.0
access_token Optional[str]

Mapbox access token. If None, reads from MAPBOX_TOKEN env var.

None
controls Optional[Dict[str, Any]]

Dict of controls to add (e.g., {"navigation": True}).

None
**kwargs

Additional widget arguments.

{}
Source code in anymap_ts/mapbox.py
def __init__(
    self,
    center: Tuple[float, float] = (0.0, 0.0),
    zoom: float = 2.0,
    width: str = "100%",
    height: str = "600px",
    style: str = "mapbox://styles/mapbox/streets-v12",
    bearing: float = 0.0,
    pitch: float = 0.0,
    max_pitch: float = 85.0,
    access_token: Optional[str] = None,
    controls: Optional[Dict[str, Any]] = None,
    **kwargs,
):
    """Initialize a Mapbox map.

    Args:
        center: Map center as (longitude, latitude).
        zoom: Initial zoom level.
        width: Map width as CSS string.
        height: Map height as CSS string.
        style: Mapbox style URL (e.g., "mapbox://styles/mapbox/streets-v12").
        bearing: Map bearing in degrees.
        pitch: Map pitch in degrees.
        max_pitch: Maximum pitch angle in degrees (default: 85).
        access_token: Mapbox access token. If None, reads from MAPBOX_TOKEN env var.
        controls: Dict of controls to add (e.g., {"navigation": True}).
        **kwargs: Additional widget arguments.
    """
    # Get access token
    token = access_token or get_mapbox_token()
    if not token:
        print(
            "Warning: No Mapbox access token provided. "
            "Set MAPBOX_TOKEN environment variable or pass access_token parameter."
        )

    super().__init__(
        center=list(center),
        zoom=zoom,
        width=width,
        height=height,
        style=style,
        bearing=bearing,
        pitch=pitch,
        max_pitch=max_pitch,
        access_token=token,
        **kwargs,
    )

    # Initialize layer dictionary
    self._layer_dict = {"Background": []}

    # Add default controls
    if controls is None:
        controls = {"navigation": True, "fullscreen": True}

    for control_name, config in controls.items():
        if config:
            self.add_control(
                control_name, **(config if isinstance(config, dict) else {})
            )

add_3d_buildings(self, source='openmaptiles', min_zoom=14, fill_extrusion_color='#aaa', fill_extrusion_opacity=0.6, height_property='render_height', base_property='render_min_height', layer_id=None, **kwargs)

Add 3D building extrusions from vector tiles.

Source code in anymap_ts/mapbox.py
def add_3d_buildings(
    self,
    source: str = "openmaptiles",
    min_zoom: float = 14,
    fill_extrusion_color: str = "#aaa",
    fill_extrusion_opacity: float = 0.6,
    height_property: str = "render_height",
    base_property: str = "render_min_height",
    layer_id: Optional[str] = None,
    **kwargs,
) -> None:
    """Add 3D building extrusions from vector tiles."""
    layer_name = layer_id or "3d-buildings"

    self.call_js_method(
        "add3DBuildings",
        source=source,
        minZoom=min_zoom,
        fillExtrusionColor=fill_extrusion_color,
        fillExtrusionOpacity=fill_extrusion_opacity,
        heightProperty=height_property,
        baseProperty=base_property,
        layerId=layer_name,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_name: {
            "id": layer_name,
            "type": "fill-extrusion",
        },
    }
    self._add_to_layer_dict(layer_name, "Vector")

add_3d_terrain(self, exaggeration=1.0, source='mapbox-dem', **kwargs)

Alias for add_terrain for MapLibre compatibility.

Source code in anymap_ts/mapbox.py
def add_3d_terrain(
    self, exaggeration: float = 1.0, source: str = "mapbox-dem", **kwargs
) -> None:
    """Alias for add_terrain for MapLibre compatibility."""
    self.add_terrain(exaggeration=exaggeration, source=source)

add_arc_layer(self, data, name=None, get_source_position='source', get_target_position='target', get_source_color=None, get_target_color=None, get_width=1, get_height=1, great_circle=False, pickable=True, opacity=0.8, **kwargs)

Add an arc layer for origin-destination visualization using deck.gl.

Arc layers are ideal for visualizing connections between locations, such as flight routes, migration patterns, or network flows.

Parameters:

Name Type Description Default
data Any

Array of data objects with source/target coordinates. Each object should have source and target positions.

required
name Optional[str]

Layer ID. If None, auto-generated.

None
get_source_position Union[str, Any]

Accessor for source position [lng, lat]. Can be a string (property name) or a value.

'source'
get_target_position Union[str, Any]

Accessor for target position [lng, lat]. Can be a string (property name) or a value.

'target'
get_source_color Optional[List[int]]

Source end color as [r, g, b, a]. Default: [51, 136, 255, 255] (blue).

None
get_target_color Optional[List[int]]

Target end color as [r, g, b, a]. Default: [255, 136, 51, 255] (orange).

None
get_width Union[float, str]

Arc width in pixels. Can be a number or accessor.

1
get_height float

Arc height multiplier. Higher values create more curved arcs.

1
great_circle bool

Whether to draw arcs along great circles.

False
pickable bool

Whether layer responds to hover/click events.

True
opacity float

Layer opacity (0-1).

0.8
**kwargs

Additional ArcLayer props.

{}

Examples:

>>> from anymap_ts import MapboxMap
>>> m = MapboxMap()
>>> arcs = [
...     {"source": [-122.4, 37.8], "target": [-73.9, 40.7]},
...     {"source": [-122.4, 37.8], "target": [-0.1, 51.5]},
... ]
>>> m.add_arc_layer(arcs, name="flights")
Source code in anymap_ts/mapbox.py
def add_arc_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_source_position: Union[str, Any] = "source",
    get_target_position: Union[str, Any] = "target",
    get_source_color: Optional[List[int]] = None,
    get_target_color: Optional[List[int]] = None,
    get_width: Union[float, str] = 1,
    get_height: float = 1,
    great_circle: bool = False,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add an arc layer for origin-destination visualization using deck.gl.

    Arc layers are ideal for visualizing connections between locations,
    such as flight routes, migration patterns, or network flows.

    Args:
        data: Array of data objects with source/target coordinates.
            Each object should have source and target positions.
        name: Layer ID. If None, auto-generated.
        get_source_position: Accessor for source position [lng, lat].
            Can be a string (property name) or a value.
        get_target_position: Accessor for target position [lng, lat].
            Can be a string (property name) or a value.
        get_source_color: Source end color as [r, g, b, a].
            Default: [51, 136, 255, 255] (blue).
        get_target_color: Target end color as [r, g, b, a].
            Default: [255, 136, 51, 255] (orange).
        get_width: Arc width in pixels. Can be a number or accessor.
        get_height: Arc height multiplier. Higher values create more curved arcs.
        great_circle: Whether to draw arcs along great circles.
        pickable: Whether layer responds to hover/click events.
        opacity: Layer opacity (0-1).
        **kwargs: Additional ArcLayer props.

    Example:
        >>> from anymap_ts import MapboxMap
        >>> m = MapboxMap()
        >>> arcs = [
        ...     {"source": [-122.4, 37.8], "target": [-73.9, 40.7]},
        ...     {"source": [-122.4, 37.8], "target": [-0.1, 51.5]},
        ... ]
        >>> m.add_arc_layer(arcs, name="flights")
    """
    layer_id = name or f"arc-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addArcLayer",
        id=layer_id,
        data=processed_data,
        getSourcePosition=get_source_position,
        getTargetPosition=get_target_position,
        getSourceColor=get_source_color or [51, 136, 255, 255],
        getTargetColor=get_target_color or [255, 136, 51, 255],
        getWidth=get_width,
        getHeight=get_height,
        greatCircle=great_circle,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "arc",
        },
    }
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_basemap(self, basemap='mapbox://styles/mapbox/streets-v12', attribution=None, **kwargs)

Add a basemap layer.

For Mapbox styles, use the style URL format: - "mapbox://styles/mapbox/streets-v12" - "mapbox://styles/mapbox/satellite-v9" - "mapbox://styles/mapbox/satellite-streets-v12" - "mapbox://styles/mapbox/light-v11" - "mapbox://styles/mapbox/dark-v11" - "mapbox://styles/mapbox/outdoors-v12"

Or use XYZ tile URLs for custom basemaps.

Parameters:

Name Type Description Default
basemap str

Mapbox style URL or XYZ tile URL.

'mapbox://styles/mapbox/streets-v12'
attribution Optional[str]

Custom attribution text.

None
**kwargs

Additional options.

{}
Source code in anymap_ts/mapbox.py
def add_basemap(
    self,
    basemap: str = "mapbox://styles/mapbox/streets-v12",
    attribution: Optional[str] = None,
    **kwargs,
) -> None:
    """Add a basemap layer.

    For Mapbox styles, use the style URL format:
    - "mapbox://styles/mapbox/streets-v12"
    - "mapbox://styles/mapbox/satellite-v9"
    - "mapbox://styles/mapbox/satellite-streets-v12"
    - "mapbox://styles/mapbox/light-v11"
    - "mapbox://styles/mapbox/dark-v11"
    - "mapbox://styles/mapbox/outdoors-v12"

    Or use XYZ tile URLs for custom basemaps.

    Args:
        basemap: Mapbox style URL or XYZ tile URL.
        attribution: Custom attribution text.
        **kwargs: Additional options.
    """
    # If it's a Mapbox style URL, set it as the map style
    if basemap.startswith("mapbox://"):
        self.style = basemap
        return

    # Otherwise, treat as XYZ tile URL
    try:
        url, default_attribution = get_basemap_url(basemap)
    except (ValueError, KeyError):
        url = basemap
        default_attribution = ""

    self.call_js_method(
        "addBasemap",
        url,
        attribution=attribution or default_attribution,
        name=basemap,
        **kwargs,
    )

    # Track in layer dict
    basemaps = self._layer_dict.get("Basemaps", [])
    if basemap not in basemaps:
        self._layer_dict = {
            **self._layer_dict,
            "Basemaps": basemaps + [basemap],
        }

add_bitmap_layer(self, image, bounds, name=None, opacity=1.0, visible=True, pickable=False, desaturate=0, transparent_color=None, tint_color=None, **kwargs)

Add a bitmap layer using deck.gl.

Source code in anymap_ts/mapbox.py
def add_bitmap_layer(
    self,
    image: str,
    bounds: List[float],
    name: Optional[str] = None,
    opacity: float = 1.0,
    visible: bool = True,
    pickable: bool = False,
    desaturate: float = 0,
    transparent_color: Optional[List[int]] = None,
    tint_color: Optional[List[int]] = None,
    **kwargs,
) -> None:
    """Add a bitmap layer using deck.gl."""
    layer_id = name or f"bitmap-{len(self._layers)}"

    self.call_js_method(
        "addBitmapLayer",
        id=layer_id,
        image=image,
        bounds=bounds,
        opacity=opacity,
        visible=visible,
        pickable=pickable,
        desaturate=desaturate,
        transparentColor=transparent_color or [0, 0, 0, 0],
        tintColor=tint_color or [255, 255, 255],
        **kwargs,
    )

    self._layers = {**self._layers, layer_id: {"id": layer_id, "type": "bitmap"}}
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_choropleth(self, data, column, cmap='viridis', classification='quantile', k=5, breaks=None, fill_opacity=0.7, line_color='#000000', line_width=1, legend=True, legend_title=None, hover=True, layer_id=None, fit_bounds=True, **kwargs)

Add a choropleth (thematic) map layer.

Source code in anymap_ts/mapbox.py
def add_choropleth(
    self,
    data: Any,
    column: str,
    cmap: str = "viridis",
    classification: str = "quantile",
    k: int = 5,
    breaks: Optional[List[float]] = None,
    fill_opacity: float = 0.7,
    line_color: str = "#000000",
    line_width: float = 1,
    legend: bool = True,
    legend_title: Optional[str] = None,
    hover: bool = True,
    layer_id: Optional[str] = None,
    fit_bounds: bool = True,
    **kwargs,
) -> None:
    """Add a choropleth (thematic) map layer."""
    from .utils import (
        get_choropleth_colors,
        compute_breaks,
        build_step_expression,
    )

    layer_name = layer_id or f"choropleth-{len(self._layers)}"

    geojson = to_geojson(data)

    if geojson.get("type") == "url":
        url = geojson["url"]
        geojson = fetch_geojson(url)

    features = geojson.get("features", [])
    values = []
    for feature in features:
        props = feature.get("properties", {})
        val = props.get(column)
        if val is not None:
            try:
                values.append(float(val))
            except (TypeError, ValueError):
                pass

    if not values:
        raise ValueError(f"No valid numeric values found for column '{column}'")

    computed_breaks = compute_breaks(values, classification, k, breaks)

    colors = get_choropleth_colors(cmap, k)

    step_expr = build_step_expression(column, computed_breaks, colors)

    bounds = get_bounds(geojson) if fit_bounds else None

    self.call_js_method(
        "addChoropleth",
        data=geojson,
        name=layer_name,
        column=column,
        stepExpression=step_expr,
        fillOpacity=fill_opacity,
        lineColor=line_color,
        lineWidth=line_width,
        hover=hover,
        fitBounds=fit_bounds,
        bounds=bounds,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_name: {
            "id": layer_name,
            "type": "choropleth",
            "source": f"{layer_name}-source",
            "column": column,
        },
    }
    self._add_to_layer_dict(layer_name, "Vector")

    if legend:
        title = legend_title or column
        labels = []
        for i in range(len(computed_breaks) - 1):
            low = computed_breaks[i]
            high = computed_breaks[i + 1]
            labels.append(f"{low:.1f} - {high:.1f}")

        self.add_legend(
            title=title,
            labels=labels,
            colors=colors,
            position="bottom-right",
        )

add_cluster_layer(self, data, cluster_radius=50, cluster_max_zoom=14, cluster_colors=None, cluster_steps=None, cluster_min_radius=15, cluster_max_radius=30, unclustered_color='#11b4da', unclustered_radius=8, show_cluster_count=True, name=None, zoom_on_click=True, fit_bounds=True, **kwargs)

Add a clustered point layer.

Source code in anymap_ts/mapbox.py
def add_cluster_layer(
    self,
    data: Any,
    cluster_radius: int = 50,
    cluster_max_zoom: int = 14,
    cluster_colors: Optional[List[str]] = None,
    cluster_steps: Optional[List[int]] = None,
    cluster_min_radius: int = 15,
    cluster_max_radius: int = 30,
    unclustered_color: str = "#11b4da",
    unclustered_radius: int = 8,
    show_cluster_count: bool = True,
    name: Optional[str] = None,
    zoom_on_click: bool = True,
    fit_bounds: bool = True,
    **kwargs,
) -> str:
    """Add a clustered point layer."""
    layer_id = name or f"cluster-{len(self._layers)}"

    if cluster_colors is None:
        cluster_colors = ["#51bbd6", "#f1f075", "#f28cb1"]
    if cluster_steps is None:
        cluster_steps = [100, 750]

    if len(cluster_steps) != len(cluster_colors) - 1:
        raise ValueError(
            f"cluster_steps must have {len(cluster_colors) - 1} values "
            f"(one less than cluster_colors), got {len(cluster_steps)}"
        )

    geojson = to_geojson(data)

    if geojson.get("type") == "url":
        url = geojson["url"]
        geojson = fetch_geojson(url)

    bounds = get_bounds(geojson) if fit_bounds else None

    self.call_js_method(
        "addClusterLayer",
        data=geojson,
        name=layer_id,
        clusterRadius=cluster_radius,
        clusterMaxZoom=cluster_max_zoom,
        clusterColors=cluster_colors,
        clusterSteps=cluster_steps,
        clusterMinRadius=cluster_min_radius,
        clusterMaxRadius=cluster_max_radius,
        unclusteredColor=unclustered_color,
        unclusteredRadius=unclustered_radius,
        showClusterCount=show_cluster_count,
        zoomOnClick=zoom_on_click,
        fitBounds=fit_bounds,
        bounds=bounds,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "cluster",
            "source": f"{layer_id}-source",
        },
    }
    self._add_to_layer_dict(layer_id, "Vector")
    return layer_id

add_cog_control(self, position='top-right', collapsed=True, default_url=None, load_default_url=False, default_opacity=1.0, default_colormap='viridis', default_bands='1', default_rescale_min=0, default_rescale_max=255, **kwargs)

Add a COG layer control.

Source code in anymap_ts/mapbox.py
def add_cog_control(
    self,
    position: str = "top-right",
    collapsed: bool = True,
    default_url: Optional[str] = None,
    load_default_url: bool = False,
    default_opacity: float = 1.0,
    default_colormap: str = "viridis",
    default_bands: str = "1",
    default_rescale_min: float = 0,
    default_rescale_max: float = 255,
    **kwargs,
) -> None:
    """Add a COG layer control."""
    self.call_js_method(
        "addCogControl",
        position=position,
        collapsed=collapsed,
        defaultUrl=default_url or "",
        loadDefaultUrl=load_default_url,
        defaultOpacity=default_opacity,
        defaultColormap=default_colormap,
        defaultBands=default_bands,
        defaultRescaleMin=default_rescale_min,
        defaultRescaleMax=default_rescale_max,
        **kwargs,
    )
    self._controls = {
        **self._controls,
        "cog-control": {"position": position, "collapsed": collapsed},
    }

add_cog_layer(self, url, name=None, opacity=1.0, visible=True, debug=False, debug_opacity=0.25, max_error=0.125, fit_bounds=True, before_id=None, **kwargs)

Add a Cloud Optimized GeoTIFF (COG) layer using deck.gl-raster.

This method renders COG files directly in the browser using GPU-accelerated deck.gl rendering with automatic reprojection support.

Parameters:

Name Type Description Default
url str

URL to the Cloud Optimized GeoTIFF file.

required
name Optional[str]

Layer ID. If None, auto-generated.

None
opacity float

Layer opacity (0-1).

1.0
visible bool

Whether layer is visible.

True
debug bool

Show reprojection mesh for debugging.

False
debug_opacity float

Opacity of debug mesh (0-1).

0.25
max_error float

Maximum reprojection error in pixels. Lower values create denser mesh for better accuracy.

0.125
fit_bounds bool

Whether to fit map to COG bounds after loading.

True
before_id Optional[str]

ID of layer to insert before.

None
**kwargs

Additional COGLayer props.

{}

Examples:

>>> from anymap_ts import MapboxMap
>>> m = MapboxMap()
>>> m.add_cog_layer(
...     "https://example.com/landcover.tif",
...     name="landcover",
...     opacity=0.8
... )
Source code in anymap_ts/mapbox.py
def add_cog_layer(
    self,
    url: str,
    name: Optional[str] = None,
    opacity: float = 1.0,
    visible: bool = True,
    debug: bool = False,
    debug_opacity: float = 0.25,
    max_error: float = 0.125,
    fit_bounds: bool = True,
    before_id: Optional[str] = None,
    **kwargs,
) -> None:
    """Add a Cloud Optimized GeoTIFF (COG) layer using deck.gl-raster.

    This method renders COG files directly in the browser using GPU-accelerated
    deck.gl rendering with automatic reprojection support.

    Args:
        url: URL to the Cloud Optimized GeoTIFF file.
        name: Layer ID. If None, auto-generated.
        opacity: Layer opacity (0-1).
        visible: Whether layer is visible.
        debug: Show reprojection mesh for debugging.
        debug_opacity: Opacity of debug mesh (0-1).
        max_error: Maximum reprojection error in pixels. Lower values
            create denser mesh for better accuracy.
        fit_bounds: Whether to fit map to COG bounds after loading.
        before_id: ID of layer to insert before.
        **kwargs: Additional COGLayer props.

    Example:
        >>> from anymap_ts import MapboxMap
        >>> m = MapboxMap()
        >>> m.add_cog_layer(
        ...     "https://example.com/landcover.tif",
        ...     name="landcover",
        ...     opacity=0.8
        ... )
    """
    layer_id = name or f"cog-{len(self._layers)}"

    self.call_js_method(
        "addCOGLayer",
        id=layer_id,
        geotiff=url,
        opacity=opacity,
        visible=visible,
        debug=debug,
        debugOpacity=debug_opacity,
        maxError=max_error,
        fitBounds=fit_bounds,
        beforeId=before_id,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "cog",
            "url": url,
        },
    }
    self._add_to_layer_dict(layer_id, "Raster")

add_colorbar(self, colormap='viridis', vmin=0, vmax=1, label='', units='', orientation='horizontal', position='bottom-right', bar_thickness=None, bar_length=None, ticks=None, opacity=None, colorbar_id=None, **kwargs)

Add a continuous gradient colorbar to the map.

Source code in anymap_ts/mapbox.py
def add_colorbar(
    self,
    colormap: str = "viridis",
    vmin: float = 0,
    vmax: float = 1,
    label: str = "",
    units: str = "",
    orientation: str = "horizontal",
    position: str = "bottom-right",
    bar_thickness: Optional[int] = None,
    bar_length: Optional[int] = None,
    ticks: Optional[Dict] = None,
    opacity: Optional[float] = None,
    colorbar_id: Optional[str] = None,
    **kwargs,
) -> None:
    """Add a continuous gradient colorbar to the map."""
    self._validate_position(position)

    cbar_id = (
        colorbar_id
        or f"colorbar-{len([k for k in self._controls.keys() if k.startswith('colorbar')])}"
    )

    js_kwargs: Dict[str, Any] = {
        "colormap": colormap,
        "vmin": vmin,
        "vmax": vmax,
        "label": label,
        "units": units,
        "orientation": orientation,
        "position": position,
        "colorbarId": cbar_id,
        **kwargs,
    }
    if bar_thickness is not None:
        js_kwargs["barThickness"] = bar_thickness
    if bar_length is not None:
        js_kwargs["barLength"] = bar_length
    if ticks is not None:
        js_kwargs["ticks"] = ticks
    if opacity is not None:
        js_kwargs["opacity"] = opacity

    self.call_js_method("addColorbar", **js_kwargs)

    self._controls = {
        **self._controls,
        cbar_id: {
            "type": "colorbar",
            "colormap": colormap,
            "vmin": vmin,
            "vmax": vmax,
            "label": label,
            "units": units,
            "orientation": orientation,
            "position": position,
        },
    }

add_column_layer(self, data, name=None, get_position='coordinates', get_fill_color=None, get_line_color=None, get_elevation=1000, radius=1000, disk_resolution=20, elevation_scale=1, coverage=1, extruded=True, filled=True, stroked=False, wireframe=False, pickable=True, opacity=0.8, **kwargs)

Add a column layer using deck.gl.

Source code in anymap_ts/mapbox.py
def add_column_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_position: Union[str, Any] = "coordinates",
    get_fill_color: Optional[Union[List[int], str]] = None,
    get_line_color: Optional[Union[List[int], str]] = None,
    get_elevation: Union[float, str] = 1000,
    radius: float = 1000,
    disk_resolution: int = 20,
    elevation_scale: float = 1,
    coverage: float = 1,
    extruded: bool = True,
    filled: bool = True,
    stroked: bool = False,
    wireframe: bool = False,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add a column layer using deck.gl."""
    layer_id = name or f"column-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addColumnLayer",
        id=layer_id,
        data=processed_data,
        getPosition=get_position,
        getFillColor=get_fill_color or [255, 140, 0, 200],
        getLineColor=get_line_color or [0, 0, 0, 255],
        getElevation=get_elevation,
        radius=radius,
        diskResolution=disk_resolution,
        elevationScale=elevation_scale,
        coverage=coverage,
        extruded=extruded,
        filled=filled,
        stroked=stroked,
        wireframe=wireframe,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {**self._layers, layer_id: {"id": layer_id, "type": "column"}}
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_contour_layer(self, data, name=None, get_position='coordinates', get_weight=1, cell_size=200, contours=None, pickable=True, opacity=1, **kwargs)

Add a contour layer using deck.gl.

Source code in anymap_ts/mapbox.py
def add_contour_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_position: Union[str, Any] = "coordinates",
    get_weight: Union[float, str] = 1,
    cell_size: float = 200,
    contours: Optional[List[Dict]] = None,
    pickable: bool = True,
    opacity: float = 1,
    **kwargs,
) -> None:
    """Add a contour layer using deck.gl."""
    layer_id = name or f"contour-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    default_contours = [
        {"threshold": 1, "color": [255, 255, 255], "strokeWidth": 1},
        {"threshold": 5, "color": [51, 136, 255], "strokeWidth": 2},
        {"threshold": 10, "color": [0, 0, 255], "strokeWidth": 3},
    ]

    self.call_js_method(
        "addContourLayer",
        id=layer_id,
        data=processed_data,
        getPosition=get_position,
        getWeight=get_weight,
        cellSize=cell_size,
        contours=contours or default_contours,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {**self._layers, layer_id: {"id": layer_id, "type": "contour"}}
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_control(self, control_type, position='top-right', **kwargs)

Add a map control.

Parameters:

Name Type Description Default
control_type str

Type of control ('navigation', 'scale', 'fullscreen', etc.).

required
position str

Control position.

'top-right'
**kwargs

Control-specific options.

{}
Source code in anymap_ts/mapbox.py
def add_control(
    self,
    control_type: str,
    position: str = "top-right",
    **kwargs,
) -> None:
    """Add a map control.

    Args:
        control_type: Type of control ('navigation', 'scale', 'fullscreen', etc.).
        position: Control position.
        **kwargs: Control-specific options.
    """
    self.call_js_method("addControl", control_type, position=position, **kwargs)
    self._controls = {
        **self._controls,
        control_type: {"type": control_type, "position": position, **kwargs},
    }

add_control_grid(self, position='top-right', default_controls=None, exclude=None, rows=None, columns=None, collapsed=True, collapsible=True, title='', show_row_column_controls=True, gap=2, basemap_style_url=None, exclude_layers=None, **kwargs)

Add a ControlGrid with all default tools or a custom subset.

Source code in anymap_ts/mapbox.py
def add_control_grid(
    self,
    position: str = "top-right",
    default_controls: Optional[List[str]] = None,
    exclude: Optional[List[str]] = None,
    rows: Optional[int] = None,
    columns: Optional[int] = None,
    collapsed: bool = True,
    collapsible: bool = True,
    title: str = "",
    show_row_column_controls: bool = True,
    gap: int = 2,
    basemap_style_url: Optional[str] = None,
    exclude_layers: Optional[List[str]] = None,
    **kwargs,
) -> None:
    """Add a ControlGrid with all default tools or a custom subset."""
    js_kwargs: Dict[str, Any] = {
        "position": position,
        "collapsed": collapsed,
        "collapsible": collapsible,
        "showRowColumnControls": show_row_column_controls,
        "gap": gap,
        **kwargs,
    }
    if default_controls is not None:
        js_kwargs["defaultControls"] = default_controls
    if exclude is not None:
        js_kwargs["exclude"] = exclude
    if rows is not None:
        js_kwargs["rows"] = rows
    if columns is not None:
        js_kwargs["columns"] = columns
    if title:
        js_kwargs["title"] = title
    if basemap_style_url is not None:
        js_kwargs["basemapStyleUrl"] = basemap_style_url
    if exclude_layers is not None:
        js_kwargs["excludeLayers"] = exclude_layers

    self.call_js_method("addControlGrid", **js_kwargs)
    self._controls = {
        **self._controls,
        "control-grid": {
            "position": position,
            "collapsed": collapsed,
            "collapsible": collapsible,
        },
    }

add_coordinates_control(self, position='bottom-left', precision=4)

Add a coordinates display control.

Source code in anymap_ts/mapbox.py
def add_coordinates_control(
    self,
    position: str = "bottom-left",
    precision: int = 4,
) -> None:
    """Add a coordinates display control."""
    self.call_js_method(
        "addCoordinatesControl",
        position=position,
        precision=precision,
    )

add_deck_heatmap_layer(self, data, name=None, get_position='coordinates', get_weight=1, radius_pixels=30, intensity=1, threshold=0.05, color_range=None, opacity=1, **kwargs)

Add a GPU-accelerated heatmap layer using deck.gl.

Source code in anymap_ts/mapbox.py
def add_deck_heatmap_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_position: Union[str, Any] = "coordinates",
    get_weight: Union[float, str] = 1,
    radius_pixels: float = 30,
    intensity: float = 1,
    threshold: float = 0.05,
    color_range: Optional[List[List[int]]] = None,
    opacity: float = 1,
    **kwargs,
) -> None:
    """Add a GPU-accelerated heatmap layer using deck.gl."""
    layer_id = name or f"deck-heatmap-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    default_color_range = [
        [255, 255, 178, 25],
        [254, 217, 118, 85],
        [254, 178, 76, 127],
        [253, 141, 60, 170],
        [240, 59, 32, 212],
        [189, 0, 38, 255],
    ]

    self.call_js_method(
        "addHeatmapLayer",
        id=layer_id,
        data=processed_data,
        getPosition=get_position,
        getWeight=get_weight,
        radiusPixels=radius_pixels,
        intensity=intensity,
        threshold=threshold,
        colorRange=color_range or default_color_range,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {"id": layer_id, "type": "deck-heatmap"},
    }
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_deckgl_layer(self, layer_type, data, name=None, **kwargs)

Add a generic deck.gl layer to the map.

Source code in anymap_ts/mapbox.py
def add_deckgl_layer(
    self,
    layer_type: str,
    data: Any,
    name: Optional[str] = None,
    **kwargs,
) -> None:
    """Add a generic deck.gl layer to the map."""
    layer_type_clean = layer_type.replace("Layer", "")
    prefix = layer_type_clean.lower()
    layer_id = name or f"{prefix}-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addDeckGLLayer",
        layerType=layer_type,
        id=layer_id,
        data=processed_data,
        **kwargs,
    )

    self._layers = {**self._layers, layer_id: {"id": layer_id, "type": layer_type}}
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_draw_control(self, position='top-right', draw_modes=None, edit_modes=None, collapsed=False, **kwargs)

Add a drawing control.

Source code in anymap_ts/mapbox.py
def add_draw_control(
    self,
    position: str = "top-right",
    draw_modes: Optional[List[str]] = None,
    edit_modes: Optional[List[str]] = None,
    collapsed: bool = False,
    **kwargs,
) -> None:
    """Add a drawing control."""
    if draw_modes is None:
        draw_modes = ["polygon", "line", "rectangle", "circle", "marker"]
    if edit_modes is None:
        edit_modes = ["select", "drag", "change", "rotate", "delete"]

    self.call_js_method(
        "addDrawControl",
        position=position,
        drawModes=draw_modes,
        editModes=edit_modes,
        collapsed=collapsed,
        **kwargs,
    )
    self._controls = {
        **self._controls,
        "draw-control": {
            "position": position,
            "drawModes": draw_modes,
            "editModes": edit_modes,
        },
    }

add_flatgeobuf(self, url, name=None, layer_type=None, paint=None, fit_bounds=True, **kwargs)

Add a FlatGeobuf layer from a URL.

Source code in anymap_ts/mapbox.py
def add_flatgeobuf(
    self,
    url: str,
    name: Optional[str] = None,
    layer_type: Optional[str] = None,
    paint: Optional[Dict] = None,
    fit_bounds: bool = True,
    **kwargs,
) -> None:
    """Add a FlatGeobuf layer from a URL."""
    layer_id = name or f"flatgeobuf-{len(self._layers)}"

    self.call_js_method(
        "addFlatGeobuf",
        url=url,
        name=layer_id,
        layerType=layer_type,
        paint=paint,
        fitBounds=fit_bounds,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "flatgeobuf",
            "url": url,
        },
    }
    self._add_to_layer_dict(layer_id, "Vector")

add_geojson(self, data, layer_type=None, paint=None, name=None, fit_bounds=True, **kwargs)

Add GeoJSON data to the map.

Parameters:

Name Type Description Default
data Union[str, Dict]

GeoJSON dict or URL to GeoJSON file.

required
layer_type Optional[str]

Mapbox layer type.

None
paint Optional[Dict]

Mapbox paint properties.

None
name Optional[str]

Layer name.

None
fit_bounds bool

Whether to fit map to data bounds.

True
**kwargs

Additional layer options.

{}
Source code in anymap_ts/mapbox.py
def add_geojson(
    self,
    data: Union[str, Dict],
    layer_type: Optional[str] = None,
    paint: Optional[Dict] = None,
    name: Optional[str] = None,
    fit_bounds: bool = True,
    **kwargs,
) -> None:
    """Add GeoJSON data to the map.

    Args:
        data: GeoJSON dict or URL to GeoJSON file.
        layer_type: Mapbox layer type.
        paint: Mapbox paint properties.
        name: Layer name.
        fit_bounds: Whether to fit map to data bounds.
        **kwargs: Additional layer options.
    """
    self.add_vector(
        data,
        layer_type=layer_type,
        paint=paint,
        name=name,
        fit_bounds=fit_bounds,
        **kwargs,
    )

add_geojson_layer(self, data, name=None, get_fill_color=None, get_line_color=None, get_line_width=1, get_point_radius=5, get_elevation=0, extruded=False, wireframe=False, filled=True, stroked=True, line_width_min_pixels=1, point_radius_min_pixels=2, pickable=True, opacity=0.8, **kwargs)

Add a GeoJSON layer with auto-styling using deck.gl.

Source code in anymap_ts/mapbox.py
def add_geojson_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_fill_color: Optional[Union[List[int], str]] = None,
    get_line_color: Optional[Union[List[int], str]] = None,
    get_line_width: Union[float, str] = 1,
    get_point_radius: Union[float, str] = 5,
    get_elevation: Union[float, str] = 0,
    extruded: bool = False,
    wireframe: bool = False,
    filled: bool = True,
    stroked: bool = True,
    line_width_min_pixels: float = 1,
    point_radius_min_pixels: float = 2,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add a GeoJSON layer with auto-styling using deck.gl."""
    layer_id = name or f"geojson-deck-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addGeoJsonLayer",
        id=layer_id,
        data=processed_data,
        getFillColor=get_fill_color or [51, 136, 255, 128],
        getLineColor=get_line_color or [0, 0, 0, 255],
        getLineWidth=get_line_width,
        getPointRadius=get_point_radius,
        getElevation=get_elevation,
        extruded=extruded,
        wireframe=wireframe,
        filled=filled,
        stroked=stroked,
        lineWidthMinPixels=line_width_min_pixels,
        pointRadiusMinPixels=point_radius_min_pixels,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {"id": layer_id, "type": "geojson-deck"},
    }
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_grid_cell_layer(self, data, name=None, get_position='coordinates', get_color=None, get_elevation=1000, cell_size=200, coverage=1, elevation_scale=1, extruded=True, pickable=True, opacity=0.8, **kwargs)

Add a grid cell layer using deck.gl.

Source code in anymap_ts/mapbox.py
def add_grid_cell_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_position: Union[str, Any] = "coordinates",
    get_color: Optional[Union[List[int], str]] = None,
    get_elevation: Union[float, str] = 1000,
    cell_size: float = 200,
    coverage: float = 1,
    elevation_scale: float = 1,
    extruded: bool = True,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add a grid cell layer using deck.gl."""
    layer_id = name or f"gridcell-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addGridCellLayer",
        id=layer_id,
        data=processed_data,
        getPosition=get_position,
        getColor=get_color or [255, 140, 0, 200],
        getElevation=get_elevation,
        cellSize=cell_size,
        coverage=coverage,
        elevationScale=elevation_scale,
        extruded=extruded,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {"id": layer_id, "type": "gridcell"},
    }
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_grid_layer(self, data, name=None, get_position='coordinates', cell_size=200, elevation_scale=4, extruded=True, color_range=None, pickable=True, opacity=0.8, **kwargs)

Add a grid layer using deck.gl.

Source code in anymap_ts/mapbox.py
def add_grid_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_position: Union[str, Any] = "coordinates",
    cell_size: float = 200,
    elevation_scale: float = 4,
    extruded: bool = True,
    color_range: Optional[List[List[int]]] = None,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add a grid layer using deck.gl."""
    layer_id = name or f"grid-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    default_color_range = [
        [1, 152, 189],
        [73, 227, 206],
        [216, 254, 181],
        [254, 237, 177],
        [254, 173, 84],
        [209, 55, 78],
    ]

    self.call_js_method(
        "addGridLayer",
        id=layer_id,
        data=processed_data,
        getPosition=get_position,
        cellSize=cell_size,
        elevationScale=elevation_scale,
        extruded=extruded,
        colorRange=color_range or default_color_range,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {**self._layers, layer_id: {"id": layer_id, "type": "grid"}}
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_heatmap(self, data, weight_property=None, radius=20, intensity=1.0, colormap=None, opacity=0.8, name=None, fit_bounds=True, **kwargs)

Add a heatmap layer to the map.

Source code in anymap_ts/mapbox.py
def add_heatmap(
    self,
    data: Any,
    weight_property: Optional[str] = None,
    radius: int = 20,
    intensity: float = 1.0,
    colormap: Optional[List] = None,
    opacity: float = 0.8,
    name: Optional[str] = None,
    fit_bounds: bool = True,
    **kwargs,
) -> None:
    """Add a heatmap layer to the map."""
    self._validate_opacity(opacity)
    layer_id = name or f"heatmap-{len(self._layers)}"

    geojson = to_geojson(data)

    if geojson.get("type") == "url":
        url = geojson["url"]
        geojson = fetch_geojson(url)

    if colormap is None:
        colormap = [
            [0, "rgba(33,102,172,0)"],
            [0.2, "rgb(103,169,207)"],
            [0.4, "rgb(209,229,240)"],
            [0.6, "rgb(253,219,199)"],
            [0.8, "rgb(239,138,98)"],
            [1, "rgb(178,24,43)"],
        ]

    paint = {
        "heatmap-radius": radius,
        "heatmap-intensity": intensity,
        "heatmap-opacity": opacity,
        "heatmap-color": [
            "interpolate",
            ["linear"],
            ["heatmap-density"],
        ],
    }

    for stop, color in colormap:
        paint["heatmap-color"].extend([stop, color])

    if weight_property:
        paint["heatmap-weight"] = ["get", weight_property]

    bounds = get_bounds(geojson) if fit_bounds else None

    self.call_js_method(
        "addGeoJSON",
        data=geojson,
        name=layer_id,
        layerType="heatmap",
        paint=paint,
        fitBounds=fit_bounds,
        bounds=bounds,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "heatmap",
            "source": f"{layer_id}-source",
            "paint": paint,
        },
    }
    self._add_to_layer_dict(layer_id, "Heatmap")

add_hexagon_layer(self, data, name=None, get_position='coordinates', radius=1000, elevation_scale=4, extruded=True, color_range=None, pickable=True, opacity=0.8, **kwargs)

Add a hexagon layer using deck.gl.

Source code in anymap_ts/mapbox.py
def add_hexagon_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_position: Union[str, Any] = "coordinates",
    radius: float = 1000,
    elevation_scale: float = 4,
    extruded: bool = True,
    color_range: Optional[List[List[int]]] = None,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add a hexagon layer using deck.gl."""
    layer_id = name or f"hexagon-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    default_color_range = [
        [1, 152, 189],
        [73, 227, 206],
        [216, 254, 181],
        [254, 237, 177],
        [254, 173, 84],
        [209, 55, 78],
    ]

    self.call_js_method(
        "addHexagonLayer",
        id=layer_id,
        data=processed_data,
        getPosition=get_position,
        radius=radius,
        elevationScale=elevation_scale,
        extruded=extruded,
        colorRange=color_range or default_color_range,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {**self._layers, layer_id: {"id": layer_id, "type": "hexagon"}}
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_hover_effect(self, layer_id, highlight_color=None, highlight_opacity=None, highlight_outline_width=2, **kwargs)

Add hover highlight effect to an existing layer.

Source code in anymap_ts/mapbox.py
def add_hover_effect(
    self,
    layer_id: str,
    highlight_color: Optional[str] = None,
    highlight_opacity: Optional[float] = None,
    highlight_outline_width: float = 2,
    **kwargs,
) -> None:
    """Add hover highlight effect to an existing layer."""
    self.call_js_method(
        "addHoverEffect",
        layerId=layer_id,
        highlightColor=highlight_color,
        highlightOpacity=highlight_opacity,
        highlightOutlineWidth=highlight_outline_width,
        **kwargs,
    )

add_icon_layer(self, data, name=None, get_position='coordinates', get_icon='icon', get_size=20, get_color=None, icon_atlas=None, icon_mapping=None, pickable=True, opacity=1, **kwargs)

Add an icon layer using deck.gl.

Source code in anymap_ts/mapbox.py
def add_icon_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_position: Union[str, Any] = "coordinates",
    get_icon: Union[str, Any] = "icon",
    get_size: Union[float, str] = 20,
    get_color: Optional[Union[List[int], str]] = None,
    icon_atlas: Optional[str] = None,
    icon_mapping: Optional[Dict] = None,
    pickable: bool = True,
    opacity: float = 1,
    **kwargs,
) -> None:
    """Add an icon layer using deck.gl."""
    layer_id = name or f"icon-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addIconLayer",
        id=layer_id,
        data=processed_data,
        getPosition=get_position,
        getIcon=get_icon,
        getSize=get_size,
        getColor=get_color or [255, 255, 255, 255],
        iconAtlas=icon_atlas,
        iconMapping=icon_mapping,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {**self._layers, layer_id: {"id": layer_id, "type": "icon"}}
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_image(self, name, url)

Load a custom icon image for use in symbol layers.

Source code in anymap_ts/mapbox.py
def add_image(self, name: str, url: str) -> None:
    """Load a custom icon image for use in symbol layers."""
    self.call_js_method("addMapImage", name=name, url=url)

add_image_layer(self, url, coordinates, name=None, opacity=1.0, **kwargs)

Add a georeferenced image overlay.

Source code in anymap_ts/mapbox.py
def add_image_layer(
    self,
    url: str,
    coordinates: List[List[float]],
    name: Optional[str] = None,
    opacity: float = 1.0,
    **kwargs,
) -> None:
    """Add a georeferenced image overlay."""
    self._validate_opacity(opacity)
    layer_id = name or f"image-{len(self._layers)}"

    if len(coordinates) != 4:
        raise ValueError(
            "coordinates must have exactly 4 corner points "
            "[top-left, top-right, bottom-right, bottom-left]"
        )

    self.call_js_method(
        "addImageLayer",
        id=layer_id,
        url=url,
        coordinates=coordinates,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "image",
            "url": url,
            "coordinates": coordinates,
        },
    }
    self._add_to_layer_dict(layer_id, "Raster")

add_layer(self, layer_id, layer_type, source, paint=None, layout=None, before_id=None, **kwargs)

Add a generic layer to the map.

Parameters:

Name Type Description Default
layer_id str

Unique layer identifier.

required
layer_type str

Mapbox layer type.

required
source Union[str, Dict]

Source ID or source configuration dict.

required
paint Optional[Dict]

Paint properties.

None
layout Optional[Dict]

Layout properties.

None
before_id Optional[str]

ID of layer to insert before.

None
**kwargs

Additional layer options.

{}
Source code in anymap_ts/mapbox.py
def add_layer(
    self,
    layer_id: str,
    layer_type: str,
    source: Union[str, Dict],
    paint: Optional[Dict] = None,
    layout: Optional[Dict] = None,
    before_id: Optional[str] = None,
    **kwargs,
) -> None:
    """Add a generic layer to the map.

    Args:
        layer_id: Unique layer identifier.
        layer_type: Mapbox layer type.
        source: Source ID or source configuration dict.
        paint: Paint properties.
        layout: Layout properties.
        before_id: ID of layer to insert before.
        **kwargs: Additional layer options.
    """
    layer_config = {
        "id": layer_id,
        "type": layer_type,
        "paint": paint or {},
        "layout": layout or {},
        **kwargs,
    }

    if isinstance(source, str):
        layer_config["source"] = source
    else:
        source_id = f"{layer_id}-source"
        self._sources = {**self._sources, source_id: source}
        self.call_js_method("addSource", source_id, **source)
        layer_config["source"] = source_id

    self._layers = {**self._layers, layer_id: layer_config}
    self.call_js_method("addLayer", beforeId=before_id, **layer_config)
    lt = layer_config.get("type", "")
    self._add_to_layer_dict(layer_id, "Raster" if lt == "raster" else "Vector")

add_layer_control(self, layers=None, position='top-right', collapsed=True)

Add a layer visibility control.

Source code in anymap_ts/mapbox.py
def add_layer_control(
    self,
    layers: Optional[List[str]] = None,
    position: str = "top-right",
    collapsed: bool = True,
) -> None:
    """Add a layer visibility control."""
    if layers is None:
        layers = list(self._layers.keys())

    self.call_js_method(
        "addLayerControl",
        layers=layers,
        position=position,
        collapsed=collapsed,
    )
    self._controls = {
        **self._controls,
        "layer-control": {
            "layers": layers,
            "position": position,
            "collapsed": collapsed,
        },
    }

add_legend(self, title, labels, colors, position='bottom-right', opacity=1.0, legend_id=None, **kwargs)

Add a floating legend control to the map.

Source code in anymap_ts/mapbox.py
def add_legend(
    self,
    title: str,
    labels: List[str],
    colors: List[str],
    position: str = "bottom-right",
    opacity: float = 1.0,
    legend_id: Optional[str] = None,
    **kwargs,
) -> None:
    """Add a floating legend control to the map."""
    if len(labels) != len(colors):
        raise ValueError("Number of labels must match number of colors")

    self._validate_position(position)

    for i, color in enumerate(colors):
        if not isinstance(color, str) or not color.startswith("#"):
            raise ValueError(
                f"Color at index {i} must be a hex color string (e.g., '#ff0000')"
            )

    legend_id = (
        legend_id
        or f"legend-{len([k for k in self._controls.keys() if k.startswith('legend')])}"
    )

    legend_items = [
        {"label": label, "color": color} for label, color in zip(labels, colors)
    ]

    self.call_js_method(
        "addLegend",
        id=legend_id,
        title=title,
        items=legend_items,
        position=position,
        opacity=opacity,
        **kwargs,
    )

    self._controls = {
        **self._controls,
        legend_id: {
            "type": "legend",
            "title": title,
            "labels": labels,
            "colors": colors,
            "position": position,
            "opacity": opacity,
        },
    }

add_lidar_control(self, position='top-right', collapsed=True, title='LiDAR Viewer', point_size=2, opacity=1.0, color_scheme='elevation', use_percentile=True, point_budget=1000000, pickable=False, auto_zoom=True, copc_loading_mode=None, streaming_point_budget=5000000, **kwargs)

Add an interactive LiDAR control panel.

The LiDAR control provides a UI panel for loading, visualizing, and styling LiDAR point cloud files (LAS, LAZ, COPC formats).

Parameters:

Name Type Description Default
position str

Control position ('top-left', 'top-right', 'bottom-left', 'bottom-right').

'top-right'
collapsed bool

Whether the panel starts collapsed.

True
title str

Title displayed on the panel.

'LiDAR Viewer'
point_size float

Point size in pixels.

2
opacity float

Layer opacity (0-1).

1.0
color_scheme str

Color scheme ('elevation', 'intensity', 'classification', 'rgb').

'elevation'
use_percentile bool

Use 2-98% percentile for color scaling.

True
point_budget int

Maximum number of points to display.

1000000
pickable bool

Enable hover/click interactions.

False
auto_zoom bool

Auto-zoom to point cloud after loading.

True
copc_loading_mode Optional[str]

COPC loading mode ('full' or 'dynamic').

None
streaming_point_budget int

Point budget for streaming mode.

5000000
**kwargs

Additional control options.

{}

Examples:

>>> from anymap_ts import MapboxMap
>>> m = MapboxMap(pitch=60)
>>> m.add_lidar_control(color_scheme="classification", pickable=True)
Source code in anymap_ts/mapbox.py
def add_lidar_control(
    self,
    position: str = "top-right",
    collapsed: bool = True,
    title: str = "LiDAR Viewer",
    point_size: float = 2,
    opacity: float = 1.0,
    color_scheme: str = "elevation",
    use_percentile: bool = True,
    point_budget: int = 1000000,
    pickable: bool = False,
    auto_zoom: bool = True,
    copc_loading_mode: Optional[str] = None,
    streaming_point_budget: int = 5000000,
    **kwargs,
) -> None:
    """Add an interactive LiDAR control panel.

    The LiDAR control provides a UI panel for loading, visualizing, and
    styling LiDAR point cloud files (LAS, LAZ, COPC formats).

    Args:
        position: Control position ('top-left', 'top-right', 'bottom-left', 'bottom-right').
        collapsed: Whether the panel starts collapsed.
        title: Title displayed on the panel.
        point_size: Point size in pixels.
        opacity: Layer opacity (0-1).
        color_scheme: Color scheme ('elevation', 'intensity', 'classification', 'rgb').
        use_percentile: Use 2-98% percentile for color scaling.
        point_budget: Maximum number of points to display.
        pickable: Enable hover/click interactions.
        auto_zoom: Auto-zoom to point cloud after loading.
        copc_loading_mode: COPC loading mode ('full' or 'dynamic').
        streaming_point_budget: Point budget for streaming mode.
        **kwargs: Additional control options.

    Example:
        >>> from anymap_ts import MapboxMap
        >>> m = MapboxMap(pitch=60)
        >>> m.add_lidar_control(color_scheme="classification", pickable=True)
    """
    self.call_js_method(
        "addLidarControl",
        position=position,
        collapsed=collapsed,
        title=title,
        pointSize=point_size,
        opacity=opacity,
        colorScheme=color_scheme,
        usePercentile=use_percentile,
        pointBudget=point_budget,
        pickable=pickable,
        autoZoom=auto_zoom,
        copcLoadingMode=copc_loading_mode,
        streamingPointBudget=streaming_point_budget,
        **kwargs,
    )
    self._controls = {
        **self._controls,
        "lidar-control": {"position": position, "collapsed": collapsed},
    }

add_lidar_layer(self, source, name=None, color_scheme='elevation', point_size=2, opacity=1.0, pickable=True, auto_zoom=True, streaming_mode=True, point_budget=1000000, **kwargs)

Load and display a LiDAR file from URL or local path.

Supports LAS, LAZ, and COPC (Cloud-Optimized Point Cloud) formats. For local files, the file is read and sent as base64 to JavaScript. For URLs, the data is loaded directly via streaming when possible.

Parameters:

Name Type Description Default
source Union[str, Path]

URL or local file path to the LiDAR file.

required
name Optional[str]

Layer identifier. If None, auto-generated.

None
color_scheme str

Color scheme ('elevation', 'intensity', 'classification', 'rgb').

'elevation'
point_size float

Point size in pixels.

2
opacity float

Layer opacity (0-1).

1.0
pickable bool

Enable hover/click interactions.

True
auto_zoom bool

Auto-zoom to point cloud after loading.

True
streaming_mode bool

Use streaming mode for large COPC files.

True
point_budget int

Maximum number of points to display.

1000000
**kwargs

Additional layer options.

{}

Examples:

>>> from anymap_ts import MapboxMap
>>> m = MapboxMap(center=[-123.07, 44.05], zoom=14, pitch=60)
>>> m.add_lidar_layer(
...     source="https://s3.amazonaws.com/hobu-lidar/autzen-classified.copc.laz",
...     name="autzen",
...     color_scheme="classification",
... )
Source code in anymap_ts/mapbox.py
def add_lidar_layer(
    self,
    source: Union[str, Path],
    name: Optional[str] = None,
    color_scheme: str = "elevation",
    point_size: float = 2,
    opacity: float = 1.0,
    pickable: bool = True,
    auto_zoom: bool = True,
    streaming_mode: bool = True,
    point_budget: int = 1000000,
    **kwargs,
) -> None:
    """Load and display a LiDAR file from URL or local path.

    Supports LAS, LAZ, and COPC (Cloud-Optimized Point Cloud) formats.
    For local files, the file is read and sent as base64 to JavaScript.
    For URLs, the data is loaded directly via streaming when possible.

    Args:
        source: URL or local file path to the LiDAR file.
        name: Layer identifier. If None, auto-generated.
        color_scheme: Color scheme ('elevation', 'intensity', 'classification', 'rgb').
        point_size: Point size in pixels.
        opacity: Layer opacity (0-1).
        pickable: Enable hover/click interactions.
        auto_zoom: Auto-zoom to point cloud after loading.
        streaming_mode: Use streaming mode for large COPC files.
        point_budget: Maximum number of points to display.
        **kwargs: Additional layer options.

    Example:
        >>> from anymap_ts import MapboxMap
        >>> m = MapboxMap(center=[-123.07, 44.05], zoom=14, pitch=60)
        >>> m.add_lidar_layer(
        ...     source="https://s3.amazonaws.com/hobu-lidar/autzen-classified.copc.laz",
        ...     name="autzen",
        ...     color_scheme="classification",
        ... )
    """
    import base64

    layer_id = name or f"lidar-{len(self._layers)}"

    # Check if source is a local file
    source_path = Path(source) if isinstance(source, (str, Path)) else None
    is_local = source_path is not None and source_path.exists()

    if is_local:
        # Read local file and encode as base64
        with open(source_path, "rb") as f:
            file_data = f.read()
        source_b64 = base64.b64encode(file_data).decode("utf-8")

        self.call_js_method(
            "addLidarLayer",
            source=source_b64,
            name=layer_id,
            isBase64=True,
            filename=source_path.name,
            colorScheme=color_scheme,
            pointSize=point_size,
            opacity=opacity,
            pickable=pickable,
            autoZoom=auto_zoom,
            streamingMode=streaming_mode,
            pointBudget=point_budget,
            **kwargs,
        )
    else:
        # Load from URL
        self.call_js_method(
            "addLidarLayer",
            source=str(source),
            name=layer_id,
            isBase64=False,
            colorScheme=color_scheme,
            pointSize=point_size,
            opacity=opacity,
            pickable=pickable,
            autoZoom=auto_zoom,
            streamingMode=streaming_mode,
            pointBudget=point_budget,
            **kwargs,
        )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "lidar",
            "source": str(source),
        },
    }

add_line_layer(self, data, name=None, get_source_position='sourcePosition', get_target_position='targetPosition', get_color=None, get_width=1, width_min_pixels=1, pickable=True, opacity=0.8, **kwargs)

Add a line layer using deck.gl.

Source code in anymap_ts/mapbox.py
def add_line_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_source_position: Union[str, Any] = "sourcePosition",
    get_target_position: Union[str, Any] = "targetPosition",
    get_color: Optional[Union[List[int], str]] = None,
    get_width: Union[float, str] = 1,
    width_min_pixels: float = 1,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add a line layer using deck.gl."""
    layer_id = name or f"line-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addLineLayer",
        id=layer_id,
        data=processed_data,
        getSourcePosition=get_source_position,
        getTargetPosition=get_target_position,
        getColor=get_color or [51, 136, 255, 200],
        getWidth=get_width,
        widthMinPixels=width_min_pixels,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {**self._layers, layer_id: {"id": layer_id, "type": "line"}}
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_marker(self, lng, lat, popup=None, tooltip=None, color='#3388ff', draggable=False, scale=1.0, popup_max_width='240px', tooltip_max_width='240px', name=None, **kwargs)

Add a single marker to the map.

Source code in anymap_ts/mapbox.py
def add_marker(
    self,
    lng: float,
    lat: float,
    popup: Optional[str] = None,
    tooltip: Optional[str] = None,
    color: str = "#3388ff",
    draggable: bool = False,
    scale: float = 1.0,
    popup_max_width: str = "240px",
    tooltip_max_width: str = "240px",
    name: Optional[str] = None,
    **kwargs,
) -> str:
    """Add a single marker to the map."""
    marker_id = name or f"marker-{len(self._layers)}"

    self.call_js_method(
        "addMarker",
        lng,
        lat,
        id=marker_id,
        popup=popup,
        tooltip=tooltip,
        color=color,
        draggable=draggable,
        scale=scale,
        popupMaxWidth=popup_max_width,
        tooltipMaxWidth=tooltip_max_width,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        marker_id: {
            "id": marker_id,
            "type": "marker",
            "lngLat": [lng, lat],
        },
    }
    self._add_to_layer_dict(marker_id, "Markers")
    return marker_id

add_markers(self, data, lng_column=None, lat_column=None, popup_column=None, tooltip_column=None, color='#3388ff', scale=1.0, popup_max_width='240px', tooltip_max_width='240px', draggable=False, name=None, **kwargs)

Add multiple markers from data.

Source code in anymap_ts/mapbox.py
def add_markers(
    self,
    data: Any,
    lng_column: Optional[str] = None,
    lat_column: Optional[str] = None,
    popup_column: Optional[str] = None,
    tooltip_column: Optional[str] = None,
    color: str = "#3388ff",
    scale: float = 1.0,
    popup_max_width: str = "240px",
    tooltip_max_width: str = "240px",
    draggable: bool = False,
    name: Optional[str] = None,
    **kwargs,
) -> str:
    """Add multiple markers from data."""
    layer_id = name or f"markers-{len(self._layers)}"
    markers = []

    if hasattr(data, "geometry"):
        for _, row in data.iterrows():
            geom = row.geometry
            if geom.geom_type == "Point":
                marker = {"lngLat": [geom.x, geom.y]}
                if popup_column and popup_column in row:
                    marker["popup"] = str(row[popup_column])
                if tooltip_column and tooltip_column in row:
                    marker["tooltip"] = str(row[tooltip_column])
                markers.append(marker)
    elif isinstance(data, dict) and data.get("type") == "FeatureCollection":
        for feature in data.get("features", []):
            geom = feature.get("geometry", {})
            if geom.get("type") == "Point":
                coords = geom.get("coordinates", [])
                marker = {"lngLat": coords[:2]}
                props = feature.get("properties", {})
                if popup_column and popup_column in props:
                    marker["popup"] = str(props[popup_column])
                if tooltip_column and tooltip_column in props:
                    marker["tooltip"] = str(props[tooltip_column])
                markers.append(marker)
    elif isinstance(data, list):
        lng_keys = ["lng", "lon", "longitude", "x"]
        lat_keys = ["lat", "latitude", "y"]

        for item in data:
            if not isinstance(item, dict):
                continue

            lng_val = None
            lat_val = None

            if lng_column and lng_column in item:
                lng_val = item[lng_column]
            else:
                for key in lng_keys:
                    if key in item:
                        lng_val = item[key]
                        break

            if lat_column and lat_column in item:
                lat_val = item[lat_column]
            else:
                for key in lat_keys:
                    if key in item:
                        lat_val = item[key]
                        break

            if lng_val is not None and lat_val is not None:
                marker = {"lngLat": [float(lng_val), float(lat_val)]}
                if popup_column and popup_column in item:
                    marker["popup"] = str(item[popup_column])
                if tooltip_column and tooltip_column in item:
                    marker["tooltip"] = str(item[tooltip_column])
                markers.append(marker)

    if not markers:
        raise ValueError("No valid point data found in input")

    self.call_js_method(
        "addMarkers",
        id=layer_id,
        markers=markers,
        color=color,
        scale=scale,
        popupMaxWidth=popup_max_width,
        tooltipMaxWidth=tooltip_max_width,
        draggable=draggable,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "markers",
            "count": len(markers),
        },
    }
    self._add_to_layer_dict(layer_id, "Markers")
    return layer_id

add_measure_control(self, position='top-right', collapsed=True, default_mode='distance', distance_unit='kilometers', area_unit='square-kilometers', line_color='#3b82f6', fill_color='rgba(59, 130, 246, 0.2)', **kwargs)

Add a measurement control.

Source code in anymap_ts/mapbox.py
def add_measure_control(
    self,
    position: str = "top-right",
    collapsed: bool = True,
    default_mode: str = "distance",
    distance_unit: str = "kilometers",
    area_unit: str = "square-kilometers",
    line_color: str = "#3b82f6",
    fill_color: str = "rgba(59, 130, 246, 0.2)",
    **kwargs,
) -> None:
    """Add a measurement control."""
    self._validate_position(position)
    self.call_js_method(
        "addMeasureControl",
        position=position,
        collapsed=collapsed,
        defaultMode=default_mode,
        distanceUnit=distance_unit,
        areaUnit=area_unit,
        lineColor=line_color,
        fillColor=fill_color,
        **kwargs,
    )
    self._controls = {
        **self._controls,
        "measure-control": {
            "type": "measure-control",
            "position": position,
            "collapsed": collapsed,
        },
    }

add_opacity_slider(self, layer_id, position='top-right', label=None)

Add a UI slider to control layer opacity.

Source code in anymap_ts/mapbox.py
def add_opacity_slider(
    self,
    layer_id: str,
    position: str = "top-right",
    label: Optional[str] = None,
) -> None:
    """Add a UI slider to control layer opacity."""
    self.call_js_method(
        "addOpacitySlider",
        layerId=layer_id,
        position=position,
        label=label or layer_id,
    )

add_path_layer(self, data, name=None, get_path='path', get_color=None, get_width=1, width_scale=1, width_min_pixels=1, pickable=True, opacity=0.8, **kwargs)

Add a path layer using deck.gl.

Source code in anymap_ts/mapbox.py
def add_path_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_path: Union[str, Any] = "path",
    get_color: Optional[Union[List[int], str]] = None,
    get_width: Union[float, str] = 1,
    width_scale: float = 1,
    width_min_pixels: float = 1,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add a path layer using deck.gl."""
    layer_id = name or f"path-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addPathLayer",
        id=layer_id,
        data=processed_data,
        getPath=get_path,
        getColor=get_color or [51, 136, 255, 200],
        getWidth=get_width,
        widthScale=width_scale,
        widthMinPixels=width_min_pixels,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {**self._layers, layer_id: {"id": layer_id, "type": "path"}}
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_pmtiles_control(self, position='top-right', collapsed=True, default_url=None, load_default_url=False, default_opacity=1.0, default_fill_color='steelblue', default_line_color='#333', default_pickable=True, **kwargs)

Add a PMTiles layer control.

Source code in anymap_ts/mapbox.py
def add_pmtiles_control(
    self,
    position: str = "top-right",
    collapsed: bool = True,
    default_url: Optional[str] = None,
    load_default_url: bool = False,
    default_opacity: float = 1.0,
    default_fill_color: str = "steelblue",
    default_line_color: str = "#333",
    default_pickable: bool = True,
    **kwargs,
) -> None:
    """Add a PMTiles layer control."""
    self.call_js_method(
        "addPMTilesControl",
        position=position,
        collapsed=collapsed,
        defaultUrl=default_url or "",
        loadDefaultUrl=load_default_url,
        defaultOpacity=default_opacity,
        defaultFillColor=default_fill_color,
        defaultLineColor=default_line_color,
        defaultPickable=default_pickable,
        **kwargs,
    )
    self._controls = {
        **self._controls,
        "pmtiles-control": {"position": position, "collapsed": collapsed},
    }

add_pmtiles_layer(self, url, layer_id=None, style=None, opacity=1.0, visible=True, fit_bounds=False, source_type='vector', **kwargs)

Add a PMTiles layer for efficient vector or raster tile serving.

Source code in anymap_ts/mapbox.py
def add_pmtiles_layer(
    self,
    url: str,
    layer_id: Optional[str] = None,
    style: Optional[Dict[str, Any]] = None,
    opacity: float = 1.0,
    visible: bool = True,
    fit_bounds: bool = False,
    source_type: str = "vector",
    **kwargs,
) -> None:
    """Add a PMTiles layer for efficient vector or raster tile serving."""
    layer_id = layer_id or f"pmtiles-{len(self._layers)}"

    self.call_js_method(
        "addPMTilesLayer",
        url=url,
        id=layer_id,
        style=style or {},
        opacity=opacity,
        visible=visible,
        fitBounds=fit_bounds,
        sourceType=source_type,
        name=layer_id,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "pmtiles",
            "url": url,
            "source_type": source_type,
        },
    }
    category = "Vector" if source_type == "vector" else "Raster"
    self._add_to_layer_dict(layer_id, category)

add_point_cloud_layer(self, data, name=None, get_position='position', get_color=None, get_normal=None, point_size=2, size_units='pixels', pickable=True, opacity=1.0, material=True, coordinate_system=None, coordinate_origin=None, **kwargs)

Add a point cloud layer for 3D point visualization using deck.gl.

Point cloud layers render large collections of 3D points, ideal for LiDAR data, photogrammetry outputs, or any 3D point dataset.

Parameters:

Name Type Description Default
data Any

Array of point data with positions. Each point should have x, y, z coordinates (or position array).

required
name Optional[str]

Layer ID. If None, auto-generated.

None
get_position Union[str, Any]

Accessor for point position [x, y, z]. Can be a string (property name) or a value.

'position'
get_color Optional[Union[List[int], str]]

Accessor or value for point color [r, g, b, a]. Default: [255, 255, 255, 255] (white).

None
get_normal Optional[Union[str, Any]]

Accessor for point normal [nx, ny, nz] for lighting. Default: [0, 0, 1] (pointing up).

None
point_size float

Point size in pixels or meters (depends on size_units).

2
size_units str

Size units: 'pixels', 'meters', or 'common'.

'pixels'
pickable bool

Whether layer responds to hover/click events.

True
opacity float

Layer opacity (0-1).

1.0
material bool

Whether to enable lighting effects.

True
coordinate_system Optional[int]

Coordinate system for positions.

None
coordinate_origin Optional[List[float]]

Origin for coordinate system [x, y, z].

None
**kwargs

Additional PointCloudLayer props.

{}

Examples:

>>> from anymap_ts import MapboxMap
>>> m = MapboxMap(pitch=45)
>>> points = [
...     {"position": [-122.4, 37.8, 100], "color": [255, 0, 0, 255]},
...     {"position": [-122.3, 37.7, 200], "color": [0, 255, 0, 255]},
... ]
>>> m.add_point_cloud_layer(points, point_size=5)
Source code in anymap_ts/mapbox.py
def add_point_cloud_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_position: Union[str, Any] = "position",
    get_color: Optional[Union[List[int], str]] = None,
    get_normal: Optional[Union[str, Any]] = None,
    point_size: float = 2,
    size_units: str = "pixels",
    pickable: bool = True,
    opacity: float = 1.0,
    material: bool = True,
    coordinate_system: Optional[int] = None,
    coordinate_origin: Optional[List[float]] = None,
    **kwargs,
) -> None:
    """Add a point cloud layer for 3D point visualization using deck.gl.

    Point cloud layers render large collections of 3D points, ideal for
    LiDAR data, photogrammetry outputs, or any 3D point dataset.

    Args:
        data: Array of point data with positions. Each point should have
            x, y, z coordinates (or position array).
        name: Layer ID. If None, auto-generated.
        get_position: Accessor for point position [x, y, z].
            Can be a string (property name) or a value.
        get_color: Accessor or value for point color [r, g, b, a].
            Default: [255, 255, 255, 255] (white).
        get_normal: Accessor for point normal [nx, ny, nz] for lighting.
            Default: [0, 0, 1] (pointing up).
        point_size: Point size in pixels or meters (depends on size_units).
        size_units: Size units: 'pixels', 'meters', or 'common'.
        pickable: Whether layer responds to hover/click events.
        opacity: Layer opacity (0-1).
        material: Whether to enable lighting effects.
        coordinate_system: Coordinate system for positions.
        coordinate_origin: Origin for coordinate system [x, y, z].
        **kwargs: Additional PointCloudLayer props.

    Example:
        >>> from anymap_ts import MapboxMap
        >>> m = MapboxMap(pitch=45)
        >>> points = [
        ...     {"position": [-122.4, 37.8, 100], "color": [255, 0, 0, 255]},
        ...     {"position": [-122.3, 37.7, 200], "color": [0, 255, 0, 255]},
        ... ]
        >>> m.add_point_cloud_layer(points, point_size=5)
    """
    layer_id = name or f"pointcloud-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addPointCloudLayer",
        id=layer_id,
        data=processed_data,
        getPosition=get_position,
        getColor=get_color or [255, 255, 255, 255],
        getNormal=get_normal,
        pointSize=point_size,
        sizeUnits=size_units,
        pickable=pickable,
        opacity=opacity,
        material=material,
        coordinateSystem=coordinate_system,
        coordinateOrigin=coordinate_origin,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "pointcloud",
        },
    }
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_polygon_layer(self, data, name=None, get_polygon='polygon', get_fill_color=None, get_line_color=None, get_line_width=1, get_elevation=0, extruded=False, wireframe=False, filled=True, stroked=True, line_width_min_pixels=1, pickable=True, opacity=0.5, **kwargs)

Add a polygon layer using deck.gl.

Source code in anymap_ts/mapbox.py
def add_polygon_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_polygon: Union[str, Any] = "polygon",
    get_fill_color: Optional[Union[List[int], str]] = None,
    get_line_color: Optional[Union[List[int], str]] = None,
    get_line_width: Union[float, str] = 1,
    get_elevation: Union[float, str] = 0,
    extruded: bool = False,
    wireframe: bool = False,
    filled: bool = True,
    stroked: bool = True,
    line_width_min_pixels: float = 1,
    pickable: bool = True,
    opacity: float = 0.5,
    **kwargs,
) -> None:
    """Add a polygon layer using deck.gl."""
    layer_id = name or f"polygon-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addPolygonLayer",
        id=layer_id,
        data=processed_data,
        getPolygon=get_polygon,
        getFillColor=get_fill_color or [51, 136, 255, 128],
        getLineColor=get_line_color or [0, 0, 255, 255],
        getLineWidth=get_line_width,
        getElevation=get_elevation,
        extruded=extruded,
        wireframe=wireframe,
        filled=filled,
        stroked=stroked,
        lineWidthMinPixels=line_width_min_pixels,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {**self._layers, layer_id: {"id": layer_id, "type": "polygon"}}
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_popup(self, layer_id, properties=None, template=None, **kwargs)

Add popup on click for a layer.

Source code in anymap_ts/mapbox.py
def add_popup(
    self,
    layer_id: str,
    properties: Optional[List[str]] = None,
    template: Optional[str] = None,
    **kwargs,
) -> None:
    """Add popup on click for a layer."""
    self.call_js_method(
        "addPopup",
        layerId=layer_id,
        properties=properties,
        template=template,
        **kwargs,
    )

add_print_control(self, position='top-right', collapsed=True, format='png', filename='map-export', include_north_arrow=False, include_scale_bar=False, **kwargs)

Add a print/export control.

Source code in anymap_ts/mapbox.py
def add_print_control(
    self,
    position: str = "top-right",
    collapsed: bool = True,
    format: str = "png",
    filename: str = "map-export",
    include_north_arrow: bool = False,
    include_scale_bar: bool = False,
    **kwargs,
) -> None:
    """Add a print/export control."""
    self._validate_position(position)
    self.call_js_method(
        "addPrintControl",
        position=position,
        collapsed=collapsed,
        format=format,
        filename=filename,
        includeNorthArrow=include_north_arrow,
        includeScaleBar=include_scale_bar,
        **kwargs,
    )
    self._controls = {
        **self._controls,
        "print-control": {
            "type": "print-control",
            "position": position,
            "collapsed": collapsed,
        },
    }

add_raster(self, source, name=None, attribution='', indexes=None, colormap=None, vmin=None, vmax=None, nodata=None, fit_bounds=True, **kwargs)

Add a raster layer from a local file using localtileserver.

Source code in anymap_ts/mapbox.py
def add_raster(
    self,
    source: str,
    name: Optional[str] = None,
    attribution: str = "",
    indexes: Optional[List[int]] = None,
    colormap: Optional[str] = None,
    vmin: Optional[float] = None,
    vmax: Optional[float] = None,
    nodata: Optional[float] = None,
    fit_bounds: bool = True,
    **kwargs,
) -> None:
    """Add a raster layer from a local file using localtileserver."""
    try:
        from localtileserver import TileClient
    except ImportError:
        raise ImportError(
            "localtileserver is required for local raster support. "
            "Install with: pip install anymap-ts[raster]"
        )

    client = TileClient(source)

    tile_params = {}
    if indexes:
        tile_params["indexes"] = indexes
    if colormap:
        tile_params["colormap"] = colormap
    if vmin is not None or vmax is not None:
        tile_params["vmin"] = vmin if vmin is not None else client.min
        tile_params["vmax"] = vmax if vmax is not None else client.max
    if nodata is not None:
        tile_params["nodata"] = nodata

    tile_url = client.get_tile_url(**tile_params)

    layer_name = name or Path(source).stem

    self.add_tile_layer(
        tile_url,
        name=layer_name,
        attribution=attribution,
        **kwargs,
    )

    if fit_bounds:
        bounds = client.bounds()
        if bounds:
            self.fit_bounds([bounds[0], bounds[1], bounds[2], bounds[3]])

add_scatterplot_layer(self, data, name=None, get_position='coordinates', get_radius=5, get_fill_color=None, get_line_color=None, radius_scale=1, radius_min_pixels=1, radius_max_pixels=100, line_width_min_pixels=1, stroked=True, filled=True, pickable=True, opacity=0.8, **kwargs)

Add a scatterplot layer using deck.gl.

Source code in anymap_ts/mapbox.py
def add_scatterplot_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_position: Union[str, Any] = "coordinates",
    get_radius: Union[float, str] = 5,
    get_fill_color: Optional[Union[List[int], str]] = None,
    get_line_color: Optional[Union[List[int], str]] = None,
    radius_scale: float = 1,
    radius_min_pixels: float = 1,
    radius_max_pixels: float = 100,
    line_width_min_pixels: float = 1,
    stroked: bool = True,
    filled: bool = True,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add a scatterplot layer using deck.gl."""
    layer_id = name or f"scatterplot-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addScatterplotLayer",
        id=layer_id,
        data=processed_data,
        getPosition=get_position,
        getRadius=get_radius,
        getFillColor=get_fill_color or [51, 136, 255, 200],
        getLineColor=get_line_color or [255, 255, 255, 255],
        radiusScale=radius_scale,
        radiusMinPixels=radius_min_pixels,
        radiusMaxPixels=radius_max_pixels,
        lineWidthMinPixels=line_width_min_pixels,
        stroked=stroked,
        filled=filled,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {"id": layer_id, "type": "scatterplot"},
    }
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_screen_grid_layer(self, data, name=None, get_position='coordinates', get_weight=1, cell_size_pixels=50, color_range=None, pickable=True, opacity=0.8, **kwargs)

Add a screen grid layer using deck.gl.

Source code in anymap_ts/mapbox.py
def add_screen_grid_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_position: Union[str, Any] = "coordinates",
    get_weight: Union[float, str] = 1,
    cell_size_pixels: float = 50,
    color_range: Optional[List[List[int]]] = None,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add a screen grid layer using deck.gl."""
    layer_id = name or f"screengrid-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    default_color_range = [
        [255, 255, 178, 25],
        [254, 217, 118, 85],
        [254, 178, 76, 127],
        [253, 141, 60, 170],
        [240, 59, 32, 212],
        [189, 0, 38, 255],
    ]

    self.call_js_method(
        "addScreenGridLayer",
        id=layer_id,
        data=processed_data,
        getPosition=get_position,
        getWeight=get_weight,
        cellSizePixels=cell_size_pixels,
        colorRange=color_range or default_color_range,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {"id": layer_id, "type": "screengrid"},
    }
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_search_control(self, position='top-left', placeholder='Search places...', collapsed=True, fly_to_zoom=14, show_marker=True, marker_color='#4264fb', **kwargs)

Add a search/geocoder control.

Source code in anymap_ts/mapbox.py
def add_search_control(
    self,
    position: str = "top-left",
    placeholder: str = "Search places...",
    collapsed: bool = True,
    fly_to_zoom: int = 14,
    show_marker: bool = True,
    marker_color: str = "#4264fb",
    **kwargs,
) -> None:
    """Add a search/geocoder control."""
    self._validate_position(position)
    self.call_js_method(
        "addSearchControl",
        position=position,
        placeholder=placeholder,
        collapsed=collapsed,
        flyToZoom=fly_to_zoom,
        showMarker=show_marker,
        markerColor=marker_color,
        **kwargs,
    )
    self._controls = {
        **self._controls,
        "search-control": {
            "type": "search-control",
            "position": position,
            "collapsed": collapsed,
        },
    }

add_solid_polygon_layer(self, data, name=None, get_polygon='polygon', get_fill_color=None, get_line_color=None, get_elevation=0, filled=True, extruded=False, wireframe=False, elevation_scale=1, pickable=True, opacity=0.8, **kwargs)

Add a solid polygon layer using deck.gl.

Source code in anymap_ts/mapbox.py
def add_solid_polygon_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_polygon: Union[str, Any] = "polygon",
    get_fill_color: Optional[Union[List[int], str]] = None,
    get_line_color: Optional[Union[List[int], str]] = None,
    get_elevation: Union[float, str] = 0,
    filled: bool = True,
    extruded: bool = False,
    wireframe: bool = False,
    elevation_scale: float = 1,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add a solid polygon layer using deck.gl."""
    layer_id = name or f"solidpolygon-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addSolidPolygonLayer",
        id=layer_id,
        data=processed_data,
        getPolygon=get_polygon,
        getFillColor=get_fill_color or [51, 136, 255, 128],
        getLineColor=get_line_color or [0, 0, 0, 255],
        getElevation=get_elevation,
        filled=filled,
        extruded=extruded,
        wireframe=wireframe,
        elevationScale=elevation_scale,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {"id": layer_id, "type": "solidpolygon"},
    }
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_split_map(self, left_layer, right_layer, position=50)

Add a split map comparison view with a draggable divider.

Source code in anymap_ts/mapbox.py
def add_split_map(
    self,
    left_layer: str,
    right_layer: str,
    position: int = 50,
) -> None:
    """Add a split map comparison view with a draggable divider."""
    if not 0 <= position <= 100:
        raise ValueError(f"position must be between 0 and 100, got {position}")

    self.call_js_method(
        "addSplitMap",
        leftLayer=left_layer,
        rightLayer=right_layer,
        position=position,
    )

add_stac_layer(self, url=None, item=None, assets=None, colormap=None, rescale=None, opacity=1.0, layer_id=None, titiler_endpoint='https://titiler.xyz', attribution='STAC', fit_bounds=True, **kwargs)

Add a STAC (SpatioTemporal Asset Catalog) layer to the map.

Source code in anymap_ts/mapbox.py
def add_stac_layer(
    self,
    url: Optional[str] = None,
    item: Optional[Any] = None,
    assets: Optional[List[str]] = None,
    colormap: Optional[str] = None,
    rescale: Optional[List[float]] = None,
    opacity: float = 1.0,
    layer_id: Optional[str] = None,
    titiler_endpoint: str = "https://titiler.xyz",
    attribution: str = "STAC",
    fit_bounds: bool = True,
    **kwargs,
) -> None:
    """Add a STAC (SpatioTemporal Asset Catalog) layer to the map."""
    if url is None and item is None:
        raise ValueError("Either 'url' or 'item' must be provided")

    if url is not None and item is not None:
        raise ValueError("Provide either 'url' or 'item', not both")

    if item is not None:
        try:
            if hasattr(item, "to_dict") and hasattr(item, "self_href"):
                stac_url = item.self_href
                if not stac_url and hasattr(item, "links"):
                    for link in item.links:
                        if link.rel == "self":
                            stac_url = link.href
                            break
                if not stac_url:
                    raise ValueError("STAC item must have a self_href or self link")
            else:
                raise ValueError(
                    "Item must be a pystac Item object with to_dict() and self_href"
                )
        except Exception as e:
            raise ValueError(f"Invalid STAC item: {e}")
    else:
        stac_url = url

    tile_params = {"url": stac_url}
    if assets:
        tile_params["assets"] = ",".join(assets)
    if colormap:
        tile_params["colormap_name"] = colormap
    if rescale:
        if len(rescale) == 2:
            tile_params["rescale"] = f"{rescale[0]},{rescale[1]}"
        else:
            raise ValueError("rescale must be a list of two values [min, max]")

    query_string = urlencode(tile_params)
    tile_url = f"{titiler_endpoint.rstrip('/')}/stac/tiles/{{z}}/{{x}}/{{y}}?{query_string}"

    layer_name = layer_id or f"stac-{len(self._layers)}"

    self.add_tile_layer(
        url=tile_url,
        name=layer_name,
        attribution=attribution,
        **kwargs,
    )

    if fit_bounds and item is not None:
        try:
            bbox = item.bbox
            if bbox and len(bbox) == 4:
                self.fit_bounds([[bbox[0], bbox[1]], [bbox[2], bbox[3]]])
        except Exception:
            pass

add_style_switcher(self, styles, position='top-right')

Add a dropdown to switch between map styles.

Source code in anymap_ts/mapbox.py
def add_style_switcher(
    self,
    styles: Dict[str, str],
    position: str = "top-right",
) -> None:
    """Add a dropdown to switch between map styles."""
    self.call_js_method(
        "addStyleSwitcher",
        styles=styles,
        position=position,
    )

add_swipe_map(self, left_layer, right_layer)

Add a drag-to-compare swipe control for two layers.

Source code in anymap_ts/mapbox.py
def add_swipe_map(self, left_layer: str, right_layer: str) -> None:
    """Add a drag-to-compare swipe control for two layers."""
    self.call_js_method(
        "addSwipeMap",
        leftLayer=left_layer,
        rightLayer=right_layer,
    )

add_terrain(self, exaggeration=1.0, source='mapbox-dem')

Add 3D terrain to the map.

Parameters:

Name Type Description Default
exaggeration float

Terrain exaggeration factor.

1.0
source str

Terrain source ID.

'mapbox-dem'
Source code in anymap_ts/mapbox.py
def add_terrain(
    self, exaggeration: float = 1.0, source: str = "mapbox-dem"
) -> None:
    """Add 3D terrain to the map.

    Args:
        exaggeration: Terrain exaggeration factor.
        source: Terrain source ID.
    """
    self.call_js_method("addTerrain", source=source, exaggeration=exaggeration)

add_text_layer(self, data, name=None, get_position='coordinates', get_text='text', get_size=12, get_color=None, get_angle=0, text_anchor='middle', alignment_baseline='center', pickable=True, opacity=1, **kwargs)

Add a text layer using deck.gl.

Source code in anymap_ts/mapbox.py
def add_text_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_position: Union[str, Any] = "coordinates",
    get_text: Union[str, Any] = "text",
    get_size: Union[float, str] = 12,
    get_color: Optional[Union[List[int], str]] = None,
    get_angle: Union[float, str] = 0,
    text_anchor: str = "middle",
    alignment_baseline: str = "center",
    pickable: bool = True,
    opacity: float = 1,
    **kwargs,
) -> None:
    """Add a text layer using deck.gl."""
    layer_id = name or f"text-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addTextLayer",
        id=layer_id,
        data=processed_data,
        getPosition=get_position,
        getText=get_text,
        getSize=get_size,
        getColor=get_color or [0, 0, 0, 255],
        getAngle=get_angle,
        getTextAnchor=text_anchor,
        getAlignmentBaseline=alignment_baseline,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {**self._layers, layer_id: {"id": layer_id, "type": "text"}}
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_tile_layer(self, url, name=None, attribution='', min_zoom=0, max_zoom=22, **kwargs)

Add an XYZ tile layer.

Parameters:

Name Type Description Default
url str

Tile URL template with {x}, {y}, {z} placeholders.

required
name Optional[str]

Layer name.

None
attribution str

Attribution text.

''
min_zoom int

Minimum zoom level.

0
max_zoom int

Maximum zoom level.

22
**kwargs

Additional options.

{}
Source code in anymap_ts/mapbox.py
def add_tile_layer(
    self,
    url: str,
    name: Optional[str] = None,
    attribution: str = "",
    min_zoom: int = 0,
    max_zoom: int = 22,
    **kwargs,
) -> None:
    """Add an XYZ tile layer.

    Args:
        url: Tile URL template with {x}, {y}, {z} placeholders.
        name: Layer name.
        attribution: Attribution text.
        min_zoom: Minimum zoom level.
        max_zoom: Maximum zoom level.
        **kwargs: Additional options.
    """
    layer_id = name or f"tiles-{len(self._layers)}"

    self.call_js_method(
        "addTileLayer",
        url,
        name=layer_id,
        attribution=attribution,
        minZoom=min_zoom,
        maxZoom=max_zoom,
        **kwargs,
    )

    # Track layer
    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "raster",
            "source": f"{layer_id}-source",
        },
    }
    self._add_to_layer_dict(layer_id, "Raster")

add_time_slider(self, layer_id, property, min_value=0, max_value=100, step=1, position='bottom-left', label='Time', auto_play=False, interval=500)

Add a time slider to filter data by a temporal property.

Source code in anymap_ts/mapbox.py
def add_time_slider(
    self,
    layer_id: str,
    property: str,
    min_value: float = 0,
    max_value: float = 100,
    step: float = 1,
    position: str = "bottom-left",
    label: str = "Time",
    auto_play: bool = False,
    interval: int = 500,
) -> None:
    """Add a time slider to filter data by a temporal property."""
    self.call_js_method(
        "addTimeSlider",
        layerId=layer_id,
        property=property,
        min=min_value,
        max=max_value,
        step=step,
        position=position,
        label=label,
        autoPlay=auto_play,
        interval=interval,
    )

add_tooltip(self, layer_id, template=None, properties=None)

Add a tooltip that shows on feature hover.

Source code in anymap_ts/mapbox.py
def add_tooltip(
    self,
    layer_id: str,
    template: Optional[str] = None,
    properties: Optional[List[str]] = None,
) -> None:
    """Add a tooltip that shows on feature hover."""
    self.call_js_method(
        "addTooltip",
        layerId=layer_id,
        template=template or "",
        properties=properties,
    )

add_trips_layer(self, data, name=None, get_path='waypoints', get_timestamps='timestamps', get_color=None, width_min_pixels=2, trail_length=180, current_time=0, pickable=True, opacity=0.8, **kwargs)

Add a trips layer using deck.gl.

Source code in anymap_ts/mapbox.py
def add_trips_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_path: Union[str, Any] = "waypoints",
    get_timestamps: Union[str, Any] = "timestamps",
    get_color: Optional[Union[List[int], str]] = None,
    width_min_pixels: float = 2,
    trail_length: float = 180,
    current_time: float = 0,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add a trips layer using deck.gl."""
    layer_id = name or f"trips-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addTripsLayer",
        id=layer_id,
        data=processed_data,
        getPath=get_path,
        getTimestamps=get_timestamps,
        getColor=get_color or [253, 128, 93],
        widthMinPixels=width_min_pixels,
        trailLength=trail_length,
        currentTime=current_time,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {**self._layers, layer_id: {"id": layer_id, "type": "trips"}}
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_vector(self, data, layer_type=None, paint=None, name=None, fit_bounds=True, **kwargs)

Add vector data to the map.

Supports GeoJSON, GeoDataFrame, or file paths to vector formats.

Parameters:

Name Type Description Default
data Any

GeoJSON dict, GeoDataFrame, or path to vector file.

required
layer_type Optional[str]

Mapbox layer type ('circle', 'line', 'fill', 'symbol').

None
paint Optional[Dict]

Mapbox paint properties.

None
name Optional[str]

Layer name.

None
fit_bounds bool

Whether to fit map to data bounds.

True
**kwargs

Additional layer options.

{}
Source code in anymap_ts/mapbox.py
def add_vector(
    self,
    data: Any,
    layer_type: Optional[str] = None,
    paint: Optional[Dict] = None,
    name: Optional[str] = None,
    fit_bounds: bool = True,
    **kwargs,
) -> None:
    """Add vector data to the map.

    Supports GeoJSON, GeoDataFrame, or file paths to vector formats.

    Args:
        data: GeoJSON dict, GeoDataFrame, or path to vector file.
        layer_type: Mapbox layer type ('circle', 'line', 'fill', 'symbol').
        paint: Mapbox paint properties.
        name: Layer name.
        fit_bounds: Whether to fit map to data bounds.
        **kwargs: Additional layer options.
    """
    geojson = to_geojson(data)

    layer_id = name or f"vector-{len(self._layers)}"

    # Handle URL data - fetch GeoJSON to get bounds and infer layer type
    if geojson.get("type") == "url":
        url = geojson["url"]
        geojson = fetch_geojson(url)

    # Infer layer type if not specified
    if layer_type is None:
        layer_type = infer_layer_type(geojson)

    # Get default paint if not provided
    if paint is None:
        paint = get_default_paint(layer_type)

    # Get bounds (use geojson dict, not original data which may be a URL)
    bounds = get_bounds(geojson) if fit_bounds else None

    # Call JavaScript
    self.call_js_method(
        "addGeoJSON",
        data=geojson,
        name=layer_id,
        layerType=layer_type,
        paint=paint,
        fitBounds=fit_bounds,
        bounds=bounds,
        **kwargs,
    )

    # Track layer
    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": layer_type,
            "source": f"{layer_id}-source",
            "paint": paint,
        },
    }
    self._add_to_layer_dict(layer_id, "Vector")

add_vector_control(self, position='top-right', collapsed=True, default_url=None, load_default_url=False, default_opacity=1.0, default_fill_color='#3388ff', default_stroke_color='#3388ff', fit_bounds=True, **kwargs)

Add a vector layer control.

Source code in anymap_ts/mapbox.py
def add_vector_control(
    self,
    position: str = "top-right",
    collapsed: bool = True,
    default_url: Optional[str] = None,
    load_default_url: bool = False,
    default_opacity: float = 1.0,
    default_fill_color: str = "#3388ff",
    default_stroke_color: str = "#3388ff",
    fit_bounds: bool = True,
    **kwargs,
) -> None:
    """Add a vector layer control."""
    self.call_js_method(
        "addVectorControl",
        position=position,
        collapsed=collapsed,
        defaultUrl=default_url or "",
        loadDefaultUrl=load_default_url,
        defaultOpacity=default_opacity,
        defaultFillColor=default_fill_color,
        defaultStrokeColor=default_stroke_color,
        fitBounds=fit_bounds,
        **kwargs,
    )
    self._controls = {
        **self._controls,
        "vector-control": {"position": position, "collapsed": collapsed},
    }

add_video_layer(self, urls, coordinates, name=None, opacity=1.0, **kwargs)

Add a georeferenced video overlay on the map.

Source code in anymap_ts/mapbox.py
def add_video_layer(
    self,
    urls: List[str],
    coordinates: List[List[float]],
    name: Optional[str] = None,
    opacity: float = 1.0,
    **kwargs,
) -> None:
    """Add a georeferenced video overlay on the map."""
    self._validate_opacity(opacity)
    layer_id = name or f"video-{len(self._layers)}"

    if len(coordinates) != 4:
        raise ValueError(
            "coordinates must have exactly 4 corner points "
            "[top-left, top-right, bottom-right, bottom-left]"
        )

    self.call_js_method(
        "addVideoLayer",
        id=layer_id,
        urls=urls,
        coordinates=coordinates,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "video",
            "source": f"{layer_id}-source",
        },
    }
    self._add_to_layer_dict(layer_id, "Raster")

add_zarr_control(self, position='top-right', collapsed=True, default_url=None, load_default_url=False, default_opacity=1.0, default_variable='', default_clim=None, **kwargs)

Add a Zarr layer control.

Source code in anymap_ts/mapbox.py
def add_zarr_control(
    self,
    position: str = "top-right",
    collapsed: bool = True,
    default_url: Optional[str] = None,
    load_default_url: bool = False,
    default_opacity: float = 1.0,
    default_variable: str = "",
    default_clim: Optional[Tuple[float, float]] = None,
    **kwargs,
) -> None:
    """Add a Zarr layer control."""
    self.call_js_method(
        "addZarrControl",
        position=position,
        collapsed=collapsed,
        defaultUrl=default_url or "",
        loadDefaultUrl=load_default_url,
        defaultOpacity=default_opacity,
        defaultVariable=default_variable,
        defaultClim=list(default_clim) if default_clim else [0, 1],
        **kwargs,
    )
    self._controls = {
        **self._controls,
        "zarr-control": {"position": position, "collapsed": collapsed},
    }

add_zarr_layer(self, url, variable, name=None, colormap=None, clim=None, opacity=1.0, selector=None, minzoom=0, maxzoom=22, fill_value=None, spatial_dimensions=None, zarr_version=None, bounds=None, **kwargs)

Add a Zarr dataset layer for visualizing multidimensional array data.

Source code in anymap_ts/mapbox.py
def add_zarr_layer(
    self,
    url: str,
    variable: str,
    name: Optional[str] = None,
    colormap: Optional[List[str]] = None,
    clim: Optional[Tuple[float, float]] = None,
    opacity: float = 1.0,
    selector: Optional[Dict[str, Any]] = None,
    minzoom: int = 0,
    maxzoom: int = 22,
    fill_value: Optional[float] = None,
    spatial_dimensions: Optional[Dict[str, str]] = None,
    zarr_version: Optional[int] = None,
    bounds: Optional[List[float]] = None,
    **kwargs,
) -> None:
    """Add a Zarr dataset layer for visualizing multidimensional array data."""
    layer_id = name or f"zarr-{len(self._layers)}"

    self.call_js_method(
        "addZarrLayer",
        id=layer_id,
        source=url,
        variable=variable,
        colormap=colormap or ["#000000", "#ffffff"],
        clim=list(clim) if clim else [0, 100],
        opacity=opacity,
        selector=selector or {},
        minzoom=minzoom,
        maxzoom=maxzoom,
        fillValue=fill_value,
        spatialDimensions=spatial_dimensions,
        zarrVersion=zarr_version,
        bounds=bounds,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "zarr",
            "url": url,
            "variable": variable,
        },
    }
    self._add_to_layer_dict(layer_id, "Raster")

animate_along_route(self, route, duration=10000, loop=True, marker_color='#3388ff', marker_size=1.0, show_trail=False, trail_color='#3388ff', trail_width=3, animation_id=None, **kwargs)

Animate a marker along a route.

Source code in anymap_ts/mapbox.py
def animate_along_route(
    self,
    route: Any,
    duration: int = 10000,
    loop: bool = True,
    marker_color: str = "#3388ff",
    marker_size: float = 1.0,
    show_trail: bool = False,
    trail_color: str = "#3388ff",
    trail_width: float = 3,
    animation_id: Optional[str] = None,
    **kwargs,
) -> str:
    """Animate a marker along a route."""
    anim_id = animation_id or f"animation-{len(self._layers)}"

    if isinstance(route, list) and len(route) > 0:
        if isinstance(route[0], (list, tuple)):
            coordinates = route
        else:
            raise ValueError("Route list must contain coordinate pairs")
    elif isinstance(route, dict):
        if route.get("type") == "LineString":
            coordinates = route.get("coordinates", [])
        elif route.get("type") == "Feature":
            geometry = route.get("geometry", {})
            if geometry.get("type") == "LineString":
                coordinates = geometry.get("coordinates", [])
            else:
                raise ValueError("Feature geometry must be LineString")
        elif route.get("type") == "FeatureCollection":
            features = route.get("features", [])
            if (
                features
                and features[0].get("geometry", {}).get("type") == "LineString"
            ):
                coordinates = features[0]["geometry"]["coordinates"]
            else:
                raise ValueError(
                    "FeatureCollection must contain LineString features"
                )
        else:
            raise ValueError(
                "GeoJSON must be LineString, Feature, or FeatureCollection"
            )
    else:
        geojson = to_geojson(route)
        if geojson.get("type") == "url":
            geojson = fetch_geojson(geojson["url"])
        if geojson.get("type") == "FeatureCollection":
            features = geojson.get("features", [])
            if features:
                coordinates = features[0].get("geometry", {}).get("coordinates", [])
            else:
                raise ValueError("No features found in data")
        elif geojson.get("type") == "Feature":
            coordinates = geojson.get("geometry", {}).get("coordinates", [])
        else:
            coordinates = geojson.get("coordinates", [])

    if len(coordinates) < 2:
        raise ValueError("Route must have at least 2 points")

    self.call_js_method(
        "animateAlongRoute",
        id=anim_id,
        coordinates=coordinates,
        duration=duration,
        loop=loop,
        markerColor=marker_color,
        markerSize=marker_size,
        showTrail=show_trail,
        trailColor=trail_color,
        trailWidth=trail_width,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        anim_id: {
            "id": anim_id,
            "type": "animation",
        },
    }
    return anim_id

clear_draw_data(self)

Clear all drawn features.

Source code in anymap_ts/mapbox.py
def clear_draw_data(self) -> None:
    """Clear all drawn features."""
    self._draw_data = {"type": "FeatureCollection", "features": []}
    self.call_js_method("clearDrawData")

get_draw_data(self)

Get the current drawn features as GeoJSON.

Source code in anymap_ts/mapbox.py
def get_draw_data(self) -> Dict:
    """Get the current drawn features as GeoJSON."""
    self.call_js_method("getDrawData")
    import time

    time.sleep(0.1)
    return self._draw_data or {"type": "FeatureCollection", "features": []}

get_layer(self, layer_id)

Get layer configuration by ID.

Source code in anymap_ts/mapbox.py
def get_layer(self, layer_id: str) -> Optional[Dict]:
    """Get layer configuration by ID."""
    return self._layers.get(layer_id)

get_layer_ids(self)

Get list of all layer IDs.

Source code in anymap_ts/mapbox.py
def get_layer_ids(self) -> List[str]:
    """Get list of all layer IDs."""
    return list(self._layers.keys())

get_visible_features(self, layers=None)

Get all features currently visible in the viewport.

Source code in anymap_ts/mapbox.py
def get_visible_features(
    self,
    layers: Optional[List[str]] = None,
) -> Optional[Dict]:
    """Get all features currently visible in the viewport."""
    if layers is not None:
        self.call_js_method("getVisibleFeatures", layers=layers)
    features = self._queried_features
    if features and "data" in features:
        return features["data"]
    return None

load_draw_data(self, geojson)

Load GeoJSON features into the drawing layer.

Source code in anymap_ts/mapbox.py
def load_draw_data(self, geojson: Dict) -> None:
    """Load GeoJSON features into the drawing layer."""
    self._draw_data = geojson
    self.call_js_method("loadDrawData", geojson)

move_layer(self, layer_id, before_id=None)

Move a layer in the layer stack.

Source code in anymap_ts/mapbox.py
def move_layer(self, layer_id: str, before_id: Optional[str] = None) -> None:
    """Move a layer in the layer stack."""
    self.call_js_method("moveLayer", layer_id, before_id)

pause_animation(self, animation_id)

Pause a running animation.

Source code in anymap_ts/mapbox.py
def pause_animation(self, animation_id: str) -> None:
    """Pause a running animation."""
    self.call_js_method("pauseAnimation", animation_id)

pause_video(self, name)

Pause a video layer.

Source code in anymap_ts/mapbox.py
def pause_video(self, name: str) -> None:
    """Pause a video layer."""
    self.call_js_method("pauseVideo", id=name)

play_video(self, name)

Start playing a video layer.

Source code in anymap_ts/mapbox.py
def play_video(self, name: str) -> None:
    """Start playing a video layer."""
    self.call_js_method("playVideo", id=name)

query_rendered_features(self, geometry=None, layers=None, filter_expression=None)

Query features currently rendered on the map.

Source code in anymap_ts/mapbox.py
def query_rendered_features(
    self,
    geometry: Optional[Any] = None,
    layers: Optional[List[str]] = None,
    filter_expression: Optional[List] = None,
) -> Dict:
    """Query features currently rendered on the map."""
    kwargs: Dict[str, Any] = {}
    if geometry is not None:
        kwargs["geometry"] = geometry
    if layers is not None:
        kwargs["layers"] = layers
    if filter_expression is not None:
        kwargs["filter"] = filter_expression

    self.call_js_method("queryRenderedFeatures", **kwargs)
    return self._queried_features

query_source_features(self, source_id, source_layer=None, filter_expression=None)

Query features from a source.

Source code in anymap_ts/mapbox.py
def query_source_features(
    self,
    source_id: str,
    source_layer: Optional[str] = None,
    filter_expression: Optional[List] = None,
) -> Dict:
    """Query features from a source."""
    kwargs: Dict[str, Any] = {"sourceId": source_id}
    if source_layer is not None:
        kwargs["sourceLayer"] = source_layer
    if filter_expression is not None:
        kwargs["filter"] = filter_expression

    self.call_js_method("querySourceFeatures", **kwargs)
    return self._queried_features

remove_arc_layer(self, layer_id)

Remove an arc layer.

Source code in anymap_ts/mapbox.py
def remove_arc_layer(self, layer_id: str) -> None:
    """Remove an arc layer."""
    self._remove_layer_internal(layer_id, "removeArcLayer")

remove_cluster_layer(self, layer_id)

Remove a cluster layer.

Source code in anymap_ts/mapbox.py
def remove_cluster_layer(self, layer_id: str) -> None:
    """Remove a cluster layer."""
    self._remove_layer_internal(layer_id, "removeClusterLayer")

remove_cog_layer(self, layer_id)

Remove a COG layer.

Source code in anymap_ts/mapbox.py
def remove_cog_layer(self, layer_id: str) -> None:
    """Remove a COG layer."""
    self._remove_layer_internal(layer_id, "removeCOGLayer")

remove_colorbar(self, colorbar_id=None)

Remove a colorbar from the map.

Source code in anymap_ts/mapbox.py
def remove_colorbar(self, colorbar_id: Optional[str] = None) -> None:
    """Remove a colorbar from the map."""
    if colorbar_id is None:
        cbar_keys = [k for k in self._controls.keys() if k.startswith("colorbar")]
        for key in cbar_keys:
            self.call_js_method("removeColorbar", colorbarId=key)
        self._controls = {
            k: v for k, v in self._controls.items() if not k.startswith("colorbar")
        }
    else:
        self.call_js_method("removeColorbar", colorbarId=colorbar_id)
        if colorbar_id in self._controls:
            controls = dict(self._controls)
            del controls[colorbar_id]
            self._controls = controls

remove_control(self, control_type)

Remove a map control.

Source code in anymap_ts/mapbox.py
def remove_control(self, control_type: str) -> None:
    """Remove a map control."""
    self.call_js_method("removeControl", control_type)
    if control_type in self._controls:
        controls = dict(self._controls)
        del controls[control_type]
        self._controls = controls

remove_coordinates_control(self)

Remove the coordinates display control.

Source code in anymap_ts/mapbox.py
def remove_coordinates_control(self) -> None:
    """Remove the coordinates display control."""
    self.call_js_method("removeCoordinatesControl")

remove_deck_layer(self, layer_id)

Remove a deck.gl layer from the map.

Source code in anymap_ts/mapbox.py
def remove_deck_layer(self, layer_id: str) -> None:
    """Remove a deck.gl layer from the map."""
    self._remove_layer_internal(layer_id, "removeDeckLayer")

remove_flatgeobuf(self, name)

Remove a FlatGeobuf layer from the map.

Source code in anymap_ts/mapbox.py
def remove_flatgeobuf(self, name: str) -> None:
    """Remove a FlatGeobuf layer from the map."""
    if name in self._layers:
        layers = dict(self._layers)
        del layers[name]
        self._layers = layers
    self._remove_from_layer_dict(name)
    self.call_js_method("removeFlatGeobuf", name=name)

remove_fog(self)

Remove fog atmospheric effects from the map.

Source code in anymap_ts/mapbox.py
def remove_fog(self) -> None:
    """Remove fog atmospheric effects from the map."""
    self.call_js_method("removeFog")

remove_layer(self, layer_id)

Remove a layer from the map.

Source code in anymap_ts/mapbox.py
def remove_layer(self, layer_id: str) -> None:
    """Remove a layer from the map."""
    if layer_id in self._layers:
        layers = dict(self._layers)
        del layers[layer_id]
        self._layers = layers
    self._remove_from_layer_dict(layer_id)
    self.call_js_method("removeLayer", layer_id)

remove_legend(self, legend_id=None)

Remove a legend control from the map.

Source code in anymap_ts/mapbox.py
def remove_legend(self, legend_id: Optional[str] = None) -> None:
    """Remove a legend control from the map."""
    if legend_id is None:
        legend_keys = [k for k in self._controls.keys() if k.startswith("legend")]
        for key in legend_keys:
            self.call_js_method("removeLegend", key)
        self._controls = {
            k: v for k, v in self._controls.items() if not k.startswith("legend")
        }
    else:
        self.call_js_method("removeLegend", legend_id)
        if legend_id in self._controls:
            controls = dict(self._controls)
            del controls[legend_id]
            self._controls = controls

remove_lidar_layer(self, layer_id=None)

Remove a LiDAR layer.

Parameters:

Name Type Description Default
layer_id Optional[str]

Layer identifier to remove. If None, removes all LiDAR layers.

None
Source code in anymap_ts/mapbox.py
def remove_lidar_layer(self, layer_id: Optional[str] = None) -> None:
    """Remove a LiDAR layer.

    Args:
        layer_id: Layer identifier to remove. If None, removes all LiDAR layers.
    """
    if layer_id:
        if layer_id in self._layers:
            layers = dict(self._layers)
            del layers[layer_id]
            self._layers = layers
        self.call_js_method("removeLidarLayer", id=layer_id)
    else:
        # Remove all lidar layers
        layers = dict(self._layers)
        self._layers = {k: v for k, v in layers.items() if v.get("type") != "lidar"}
        self.call_js_method("removeLidarLayer")

remove_marker(self, marker_id)

Remove a marker from the map.

Source code in anymap_ts/mapbox.py
def remove_marker(self, marker_id: str) -> None:
    """Remove a marker from the map."""
    self._remove_layer_internal(marker_id, "removeMarker")

remove_measure_control(self)

Remove the measurement control.

Source code in anymap_ts/mapbox.py
def remove_measure_control(self) -> None:
    """Remove the measurement control."""
    self.call_js_method("removeMeasureControl")
    if "measure-control" in self._controls:
        controls = dict(self._controls)
        del controls["measure-control"]
        self._controls = controls

remove_opacity_slider(self, layer_id)

Remove the opacity slider for a layer.

Source code in anymap_ts/mapbox.py
def remove_opacity_slider(self, layer_id: str) -> None:
    """Remove the opacity slider for a layer."""
    self.call_js_method("removeOpacitySlider", layerId=layer_id)

remove_pmtiles_layer(self, layer_id)

Remove a PMTiles layer.

Source code in anymap_ts/mapbox.py
def remove_pmtiles_layer(self, layer_id: str) -> None:
    """Remove a PMTiles layer."""
    self._remove_layer_internal(layer_id, "removePMTilesLayer")

remove_point_cloud_layer(self, layer_id)

Remove a point cloud layer.

Source code in anymap_ts/mapbox.py
def remove_point_cloud_layer(self, layer_id: str) -> None:
    """Remove a point cloud layer."""
    self._remove_layer_internal(layer_id, "removePointCloudLayer")

remove_print_control(self)

Remove the print/export control.

Source code in anymap_ts/mapbox.py
def remove_print_control(self) -> None:
    """Remove the print/export control."""
    self.call_js_method("removePrintControl")
    if "print-control" in self._controls:
        controls = dict(self._controls)
        del controls["print-control"]
        self._controls = controls

remove_search_control(self)

Remove the search/geocoder control.

Source code in anymap_ts/mapbox.py
def remove_search_control(self) -> None:
    """Remove the search/geocoder control."""
    self.call_js_method("removeSearchControl")
    if "search-control" in self._controls:
        controls = dict(self._controls)
        del controls["search-control"]
        self._controls = controls

remove_split_map(self)

Remove the split map comparison view.

Source code in anymap_ts/mapbox.py
def remove_split_map(self) -> None:
    """Remove the split map comparison view."""
    self.call_js_method("removeSplitMap")

remove_style_switcher(self)

Remove the style switcher control.

Source code in anymap_ts/mapbox.py
def remove_style_switcher(self) -> None:
    """Remove the style switcher control."""
    self.call_js_method("removeStyleSwitcher")

remove_swipe_map(self)

Remove the swipe map comparison control.

Source code in anymap_ts/mapbox.py
def remove_swipe_map(self) -> None:
    """Remove the swipe map comparison control."""
    self.call_js_method("removeSwipeMap")

remove_terrain(self)

Remove 3D terrain from the map.

Source code in anymap_ts/mapbox.py
def remove_terrain(self) -> None:
    """Remove 3D terrain from the map."""
    self.call_js_method("removeTerrain")

remove_time_slider(self)

Remove the time slider control.

Source code in anymap_ts/mapbox.py
def remove_time_slider(self) -> None:
    """Remove the time slider control."""
    self.call_js_method("removeTimeSlider")

remove_tooltip(self, layer_id)

Remove tooltip from a layer.

Source code in anymap_ts/mapbox.py
def remove_tooltip(self, layer_id: str) -> None:
    """Remove tooltip from a layer."""
    self.call_js_method("removeTooltip", layerId=layer_id)

remove_video_layer(self, name)

Remove a video layer from the map.

Source code in anymap_ts/mapbox.py
def remove_video_layer(self, name: str) -> None:
    """Remove a video layer from the map."""
    if name in self._layers:
        layers = dict(self._layers)
        del layers[name]
        self._layers = layers
    self._remove_from_layer_dict(name)
    self.call_js_method("removeVideoLayer", id=name)

remove_zarr_layer(self, layer_id)

Remove a Zarr layer.

Source code in anymap_ts/mapbox.py
def remove_zarr_layer(self, layer_id: str) -> None:
    """Remove a Zarr layer."""
    self._remove_layer_internal(layer_id, "removeZarrLayer")

resume_animation(self, animation_id)

Resume a paused animation.

Source code in anymap_ts/mapbox.py
def resume_animation(self, animation_id: str) -> None:
    """Resume a paused animation."""
    self.call_js_method("resumeAnimation", animation_id)

save_draw_data(self, filepath, driver=None)

Save drawn features to a file.

Source code in anymap_ts/mapbox.py
def save_draw_data(
    self,
    filepath: Union[str, Path],
    driver: Optional[str] = None,
) -> None:
    """Save drawn features to a file."""
    try:
        import geopandas as gpd
    except ImportError:
        raise ImportError(
            "geopandas is required to save draw data. "
            "Install with: pip install anymap-ts[vector]"
        )

    data = self.get_draw_data()
    if not data.get("features"):
        print("No features to save")
        return

    gdf = gpd.GeoDataFrame.from_features(data["features"])
    filepath = Path(filepath)

    if driver is None:
        ext = filepath.suffix.lower()
        driver_map = {
            ".geojson": "GeoJSON",
            ".json": "GeoJSON",
            ".shp": "ESRI Shapefile",
            ".gpkg": "GPKG",
        }
        driver = driver_map.get(ext, "GeoJSON")

    gdf.to_file(filepath, driver=driver)

seek_video(self, name, time)

Seek to a specific time in a video layer.

Source code in anymap_ts/mapbox.py
def seek_video(self, name: str, time: float) -> None:
    """Seek to a specific time in a video layer."""
    self.call_js_method("seekVideo", id=name, time=time)

set_access_token(self, token)

Set the Mapbox access token.

Parameters:

Name Type Description Default
token str

Mapbox access token.

required
Source code in anymap_ts/mapbox.py
def set_access_token(self, token: str) -> None:
    """Set the Mapbox access token.

    Args:
        token: Mapbox access token.
    """
    self.access_token = token

set_animation_speed(self, animation_id, speed)

Set animation speed multiplier.

Source code in anymap_ts/mapbox.py
def set_animation_speed(self, animation_id: str, speed: float) -> None:
    """Set animation speed multiplier."""
    self.call_js_method("setAnimationSpeed", animation_id, speed)

set_filter(self, layer_id, filter_expression=None)

Set or clear a filter on a map layer.

Source code in anymap_ts/mapbox.py
def set_filter(
    self,
    layer_id: str,
    filter_expression: Optional[List] = None,
) -> None:
    """Set or clear a filter on a map layer."""
    self.call_js_method(
        "setFilter",
        layerId=layer_id,
        filter=filter_expression,
    )

set_fog(self, color=None, high_color=None, low_color=None, horizon_blend=None, range=None, **kwargs)

Set fog atmospheric effect (Mapbox uses map.setFog() API).

Source code in anymap_ts/mapbox.py
def set_fog(
    self,
    color: Optional[str] = None,
    high_color: Optional[str] = None,
    low_color: Optional[str] = None,
    horizon_blend: Optional[float] = None,
    range: Optional[List[float]] = None,
    **kwargs,
) -> None:
    """Set fog atmospheric effect (Mapbox uses map.setFog() API)."""
    self.call_js_method(
        "setFog",
        color=color,
        highColor=high_color,
        lowColor=low_color,
        horizonBlend=horizon_blend,
        range=range,
        **kwargs,
    )

set_layout_property(self, layer_id, property_name, value)

Set a layout property for a layer.

Source code in anymap_ts/mapbox.py
def set_layout_property(
    self, layer_id: str, property_name: str, value: Any
) -> None:
    """Set a layout property for a layer."""
    self.call_js_method("setLayoutProperty", layer_id, property_name, value)

set_lidar_color_scheme(self, color_scheme)

Set the LiDAR color scheme.

Parameters:

Name Type Description Default
color_scheme str

Color scheme ('elevation', 'intensity', 'classification', 'rgb').

required
Source code in anymap_ts/mapbox.py
def set_lidar_color_scheme(self, color_scheme: str) -> None:
    """Set the LiDAR color scheme.

    Args:
        color_scheme: Color scheme ('elevation', 'intensity', 'classification', 'rgb').
    """
    self.call_js_method("setLidarColorScheme", colorScheme=color_scheme)

set_lidar_opacity(self, opacity)

Set the LiDAR layer opacity.

Parameters:

Name Type Description Default
opacity float

Opacity value between 0 and 1.

required
Source code in anymap_ts/mapbox.py
def set_lidar_opacity(self, opacity: float) -> None:
    """Set the LiDAR layer opacity.

    Args:
        opacity: Opacity value between 0 and 1.
    """
    self.call_js_method("setLidarOpacity", opacity=opacity)

set_lidar_point_size(self, point_size)

Set the LiDAR point size.

Parameters:

Name Type Description Default
point_size float

Point size in pixels.

required
Source code in anymap_ts/mapbox.py
def set_lidar_point_size(self, point_size: float) -> None:
    """Set the LiDAR point size.

    Args:
        point_size: Point size in pixels.
    """
    self.call_js_method("setLidarPointSize", pointSize=point_size)

set_opacity(self, layer_id, opacity)

Set layer opacity.

Source code in anymap_ts/mapbox.py
def set_opacity(self, layer_id: str, opacity: float) -> None:
    """Set layer opacity."""
    self._validate_opacity(opacity)
    self.call_js_method("setOpacity", layer_id, opacity)

set_paint_property(self, layer_id, property_name, value)

Set a paint property for a layer.

Source code in anymap_ts/mapbox.py
def set_paint_property(self, layer_id: str, property_name: str, value: Any) -> None:
    """Set a paint property for a layer."""
    self.call_js_method("setPaintProperty", layer_id, property_name, value)

set_projection(self, projection='mercator')

Set the map projection (Mapbox supports 'globe' and 'mercator').

Source code in anymap_ts/mapbox.py
def set_projection(self, projection: str = "mercator") -> None:
    """Set the map projection (Mapbox supports 'globe' and 'mercator')."""
    self.call_js_method("setProjection", projection=projection)

set_visibility(self, layer_id, visible)

Set layer visibility.

Parameters:

Name Type Description Default
layer_id str

Layer identifier.

required
visible bool

Whether layer should be visible.

required
Source code in anymap_ts/mapbox.py
def set_visibility(self, layer_id: str, visible: bool) -> None:
    """Set layer visibility.

    Args:
        layer_id: Layer identifier.
        visible: Whether layer should be visible.
    """
    self.call_js_method("setVisibility", layer_id, visible)

stop_animation(self, animation_id)

Stop a running animation.

Source code in anymap_ts/mapbox.py
def stop_animation(self, animation_id: str) -> None:
    """Stop a running animation."""
    self.call_js_method("stopAnimation", animation_id)
    if animation_id in self._layers:
        layers = dict(self._layers)
        del layers[animation_id]
        self._layers = layers

to_geojson(self, layer_id=None)

Get layer data as GeoJSON.

Source code in anymap_ts/mapbox.py
def to_geojson(self, layer_id: Optional[str] = None) -> Optional[Dict]:
    """Get layer data as GeoJSON."""
    if layer_id:
        self.call_js_method("getLayerData", sourceId=layer_id)
    features = self._queried_features
    if features and "data" in features:
        return features["data"]
    return None

to_geopandas(self, layer_id=None)

Get layer data as a GeoDataFrame.

Source code in anymap_ts/mapbox.py
def to_geopandas(self, layer_id: Optional[str] = None) -> Any:
    """Get layer data as a GeoDataFrame."""
    geojson = self.to_geojson(layer_id)
    if geojson is None:
        return None
    try:
        import geopandas as gpd

        return gpd.GeoDataFrame.from_features(geojson.get("features", []))
    except ImportError:
        raise ImportError("geopandas is required for to_geopandas()")

update_colorbar(self, colorbar_id=None, **kwargs)

Update an existing colorbar's properties.

Source code in anymap_ts/mapbox.py
def update_colorbar(self, colorbar_id: Optional[str] = None, **kwargs) -> None:
    """Update an existing colorbar's properties."""
    if colorbar_id is None:
        cbar_keys = [k for k in self._controls.keys() if k.startswith("colorbar")]
        if not cbar_keys:
            raise ValueError("No colorbar found to update")
        colorbar_id = cbar_keys[0]

    if colorbar_id not in self._controls:
        raise ValueError(f"Colorbar '{colorbar_id}' not found")

    js_kwargs: Dict[str, Any] = {"colorbarId": colorbar_id}
    key_map = {"bar_thickness": "barThickness", "bar_length": "barLength"}
    for key, value in kwargs.items():
        js_key = key_map.get(key, key)
        js_kwargs[js_key] = value

    self.call_js_method("updateColorbar", **js_kwargs)

update_geojson_source(self, source_id, data)

Update the data of an existing GeoJSON source in place.

Source code in anymap_ts/mapbox.py
def update_geojson_source(self, source_id: str, data: Any) -> None:
    """Update the data of an existing GeoJSON source in place."""
    processed_data = self._process_deck_data(data)
    self.call_js_method(
        "updateGeoJSONSource",
        sourceId=source_id,
        data=processed_data,
    )

update_legend(self, legend_id, title=None, labels=None, colors=None, opacity=None, **kwargs)

Update an existing legend's properties.

Source code in anymap_ts/mapbox.py
def update_legend(
    self,
    legend_id: str,
    title: Optional[str] = None,
    labels: Optional[List[str]] = None,
    colors: Optional[List[str]] = None,
    opacity: Optional[float] = None,
    **kwargs,
) -> None:
    """Update an existing legend's properties."""
    if legend_id not in self._controls:
        raise ValueError(f"Legend '{legend_id}' not found")

    update_params = {"id": legend_id}

    if title is not None:
        update_params["title"] = title
        self._controls[legend_id]["title"] = title

    if labels is not None and colors is not None:
        if len(labels) != len(colors):
            raise ValueError("Number of labels must match number of colors")

        legend_items = [
            {"label": label, "color": color} for label, color in zip(labels, colors)
        ]
        update_params["items"] = legend_items
        self._controls[legend_id]["labels"] = labels
        self._controls[legend_id]["colors"] = colors

    elif labels is not None or colors is not None:
        raise ValueError("Both labels and colors must be provided together")

    if opacity is not None:
        update_params["opacity"] = opacity
        self._controls[legend_id]["opacity"] = opacity

    update_params.update(kwargs)
    self.call_js_method("updateLegend", **update_params)

update_zarr_layer(self, layer_id, selector=None, clim=None, colormap=None, opacity=None)

Update a Zarr layer's properties dynamically.

Source code in anymap_ts/mapbox.py
def update_zarr_layer(
    self,
    layer_id: str,
    selector: Optional[Dict[str, Any]] = None,
    clim: Optional[Tuple[float, float]] = None,
    colormap: Optional[List[str]] = None,
    opacity: Optional[float] = None,
) -> None:
    """Update a Zarr layer's properties dynamically."""
    update_kwargs: Dict[str, Any] = {"id": layer_id}
    if selector is not None:
        update_kwargs["selector"] = selector
    if clim is not None:
        update_kwargs["clim"] = list(clim)
    if colormap is not None:
        update_kwargs["colormap"] = colormap
    if opacity is not None:
        update_kwargs["opacity"] = opacity
    self.call_js_method("updateZarrLayer", **update_kwargs)

get_mapbox_token()

Get Mapbox access token from environment variable.

Returns:

Type Description
str

Mapbox access token string, or empty string if not set.

Source code in anymap_ts/mapbox.py
def get_mapbox_token() -> str:
    """Get Mapbox access token from environment variable.

    Returns:
        Mapbox access token string, or empty string if not set.
    """
    return os.environ.get("MAPBOX_TOKEN", "")

maplibre

MapLibre GL JS map widget implementation.

MapLibreMap (MapWidget)

Interactive map widget using MapLibre GL JS.

This class provides a Python interface to MapLibre GL JS maps with full bidirectional communication through anywidget.

Examples:

>>> from anymap_ts import Map
>>> m = Map(center=[-122.4, 37.8], zoom=10)
>>> m.add_basemap("OpenStreetMap")
>>> m
Source code in anymap_ts/maplibre.py
class MapLibreMap(MapWidget):
    """Interactive map widget using MapLibre GL JS.

    This class provides a Python interface to MapLibre GL JS maps with
    full bidirectional communication through anywidget.

    Example:
        >>> from anymap_ts import Map
        >>> m = Map(center=[-122.4, 37.8], zoom=10)
        >>> m.add_basemap("OpenStreetMap")
        >>> m
    """

    # ESM module for frontend
    _esm = STATIC_DIR / "maplibre.js"
    _css = STATIC_DIR / "maplibre.css"

    # MapLibre-specific traits
    bearing = traitlets.Float(0.0).tag(sync=True)
    pitch = traitlets.Float(0.0).tag(sync=True)
    projection = traitlets.Unicode("mercator").tag(sync=True)
    antialias = traitlets.Bool(True).tag(sync=True)
    double_click_zoom = traitlets.Bool(True).tag(sync=True)

    # Layer tracking
    _layer_dict = traitlets.Dict({}).tag(sync=True)

    def __init__(
        self,
        center: Tuple[float, float] = (0.0, 0.0),
        zoom: float = 2.0,
        width: str = "100%",
        height: str = "700px",
        style: Union[
            str, Dict
        ] = "https://basemaps.cartocdn.com/gl/positron-gl-style/style.json",
        bearing: float = 0.0,
        pitch: float = 0.0,
        max_pitch: float = 85.0,
        projection: str = "mercator",
        controls: Optional[Dict[str, Any]] = None,
        **kwargs,
    ):
        """Initialize a MapLibre map.

        Args:
            center: Map center as (longitude, latitude).
            zoom: Initial zoom level.
            width: Map width as CSS string.
            height: Map height as CSS string. Default is "700px".
            style: MapLibre style URL or style object. Default is "https://basemaps.cartocdn.com/gl/positron-gl-style/style.json".
            bearing: Map bearing in degrees.
            pitch: Map pitch in degrees.
            max_pitch: Maximum pitch angle in degrees (default: 85).
            projection: Map projection. Supported values: 'mercator', 'globe'.
                Default is 'mercator'.
            controls: Dict of controls to add. If None, defaults to
                {"layer-control": True, "control-grid": True}.
                Use {"layer-control": {"collapsed": True}} for custom options.
            **kwargs: Additional widget arguments.
        """
        # Handle style shortcuts
        if isinstance(style, str) and not style.startswith("http"):
            try:
                style = get_maplibre_style(style)
            except ValueError:
                pass  # Use as-is

        super().__init__(
            center=list(center),
            zoom=zoom,
            width=width,
            height=height,
            style=style,
            bearing=bearing,
            pitch=pitch,
            max_pitch=max_pitch,
            projection=projection,
            **kwargs,
        )

        # Initialize layer dictionary
        self._layer_dict = {"Background": []}

        # Add default controls
        if controls is None:
            controls = {
                "layer-control": True,
                "control-grid": True,
            }

        for control_name, config in controls.items():
            if config:
                if control_name == "layer-control":
                    self.add_layer_control(
                        **(config if isinstance(config, dict) else {})
                    )
                elif control_name == "control-grid":
                    self.add_control_grid(
                        **(config if isinstance(config, dict) else {})
                    )
                else:
                    self.add_control(
                        control_name, **(config if isinstance(config, dict) else {})
                    )

    # -------------------------------------------------------------------------
    # Layer Dict Helper
    # -------------------------------------------------------------------------

    def _add_to_layer_dict(self, layer_id: str, category: str = "Overlays") -> None:
        """Add a layer to the layer dictionary for UI tracking.

        Args:
            layer_id: The layer identifier.
            category: The category to add the layer to (e.g., "Overlays", "Raster").
        """
        layers = self._layer_dict.get(category, [])
        if layer_id not in layers:
            self._layer_dict = {
                **self._layer_dict,
                category: layers + [layer_id],
            }

    def _remove_from_layer_dict(self, layer_id: str) -> None:
        """Remove a layer from the layer dictionary.

        Args:
            layer_id: The layer identifier to remove.
        """
        new_dict = {}
        for category, layers in self._layer_dict.items():
            if layer_id in layers:
                new_layers = [lid for lid in layers if lid != layer_id]
                if new_layers:  # Only keep category if it still has layers
                    new_dict[category] = new_layers
            else:
                new_dict[category] = layers
        self._layer_dict = new_dict

    # -------------------------------------------------------------------------
    # Validation Helpers
    # -------------------------------------------------------------------------

    def _validate_opacity(self, opacity: float, param_name: str = "opacity") -> float:
        """Validate opacity value is between 0 and 1.

        Args:
            opacity: The opacity value to validate.
            param_name: Name of the parameter for error messages.

        Returns:
            The validated opacity value.

        Raises:
            ValueError: If opacity is not between 0 and 1.
        """
        if not 0 <= opacity <= 1:
            raise ValueError(f"{param_name} must be between 0 and 1, got {opacity}")
        return opacity

    def _validate_position(self, position: str) -> str:
        """Validate control position is valid.

        Args:
            position: The position string to validate.

        Returns:
            The validated position string.

        Raises:
            ValueError: If position is not valid.
        """
        valid_positions = ["top-left", "top-right", "bottom-left", "bottom-right"]
        if position not in valid_positions:
            raise ValueError(
                f"Position must be one of: {', '.join(valid_positions)}, got '{position}'"
            )
        return position

    def _remove_layer_internal(self, layer_id: str, js_method: str) -> None:
        """Internal helper to remove a layer.

        Args:
            layer_id: The layer identifier to remove.
            js_method: The JavaScript method to call for removal.
        """
        if layer_id in self._layers:
            layers = dict(self._layers)
            del layers[layer_id]
            self._layers = layers
        self._remove_from_layer_dict(layer_id)
        self.call_js_method(js_method, layer_id)

    # -------------------------------------------------------------------------
    # Basemap Methods
    # -------------------------------------------------------------------------

    def add_basemap(
        self,
        basemap: str = "OpenStreetMap",
        attribution: Optional[str] = None,
        **kwargs,
    ) -> None:
        """Add a basemap layer.

        Args:
            basemap: Name of basemap provider (e.g., "OpenStreetMap", "CartoDB.Positron")
            attribution: Custom attribution text
            **kwargs: Additional options
        """
        url, default_attribution = get_basemap_url(basemap)
        self.call_js_method(
            "addBasemap",
            url,
            attribution=attribution or default_attribution,
            name=basemap,
            **kwargs,
        )

        # Track in layer dict
        basemaps = self._layer_dict.get("Basemaps", [])
        if basemap not in basemaps:
            self._layer_dict = {
                **self._layer_dict,
                "Basemaps": basemaps + [basemap],
            }

    # -------------------------------------------------------------------------
    # Vector Data Methods
    # -------------------------------------------------------------------------

    def add_vector(
        self,
        data: Any,
        layer_type: Optional[str] = None,
        paint: Optional[Dict] = None,
        name: Optional[str] = None,
        fit_bounds: bool = True,
        **kwargs,
    ) -> None:
        """Add vector data to the map.

        Supports GeoJSON, GeoDataFrame, or file paths to vector formats.

        Args:
            data: GeoJSON dict, GeoDataFrame, or path to vector file
            layer_type: MapLibre layer type ('circle', 'line', 'fill', 'symbol')
            paint: MapLibre paint properties
            name: Layer name
            fit_bounds: Whether to fit map to data bounds
            **kwargs: Additional layer options
        """
        geojson = to_geojson(data)

        layer_id = name or f"vector-{len(self._layers)}"

        # Handle URL data - fetch GeoJSON to get bounds and infer layer type
        if geojson.get("type") == "url":
            url = geojson["url"]
            # Fetch the actual GeoJSON data from URL
            geojson = fetch_geojson(url)

        # Infer layer type if not specified
        if layer_type is None:
            layer_type = infer_layer_type(geojson)

        # Get default paint if not provided
        if paint is None:
            paint = get_default_paint(layer_type)

        # Get bounds (use geojson dict, not original data which may be a URL)
        bounds = get_bounds(geojson) if fit_bounds else None

        # Call JavaScript
        self.call_js_method(
            "addGeoJSON",
            data=geojson,
            name=layer_id,
            layerType=layer_type,
            paint=paint,
            fitBounds=fit_bounds,
            bounds=bounds,
            **kwargs,
        )

        # Track layer
        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": layer_type,
                "source": f"{layer_id}-source",
                "paint": paint,
            },
        }
        self._add_to_layer_dict(layer_id, "Vector")

    def add_geojson(
        self,
        data: Union[str, Dict],
        layer_type: Optional[str] = None,
        paint: Optional[Dict] = None,
        name: Optional[str] = None,
        fit_bounds: bool = True,
        **kwargs,
    ) -> None:
        """Add GeoJSON data to the map.

        Args:
            data: GeoJSON dict or URL to GeoJSON file
            layer_type: MapLibre layer type
            paint: MapLibre paint properties
            name: Layer name
            fit_bounds: Whether to fit map to data bounds
            **kwargs: Additional layer options
        """
        self.add_vector(
            data,
            layer_type=layer_type,
            paint=paint,
            name=name,
            fit_bounds=fit_bounds,
            **kwargs,
        )

    # -------------------------------------------------------------------------
    # Marker Methods
    # -------------------------------------------------------------------------

    def add_marker(
        self,
        lng: float,
        lat: float,
        popup: Optional[str] = None,
        tooltip: Optional[str] = None,
        color: str = "#3388ff",
        draggable: bool = False,
        scale: float = 1.0,
        popup_max_width: str = "240px",
        tooltip_max_width: str = "240px",
        name: Optional[str] = None,
        **kwargs,
    ) -> str:
        """Add a single marker to the map.

        Args:
            lng: Longitude of the marker.
            lat: Latitude of the marker.
            popup: Optional popup HTML content (shown on click).
            tooltip: Optional tooltip HTML content (shown on hover).
            color: Marker color as hex string.
            draggable: Whether the marker can be dragged.
            scale: Marker size multiplier (default 1.0, range 0.1 to 3.0).
            popup_max_width: Maximum width of popup (CSS value, default "240px").
            tooltip_max_width: Maximum width of tooltip (CSS value, default "240px").
            name: Marker identifier. If None, auto-generated.
            **kwargs: Additional marker options.

        Returns:
            The marker identifier.

        Example:
            >>> from anymap_ts import Map
            >>> m = Map(center=[-122.4, 37.8], zoom=10)
            >>> m.add_marker(-122.4, 37.8, popup="San Francisco", tooltip="Hover me!")
            >>> m.add_marker(-122.5, 37.7, scale=1.5, color="#ff0000")
        """
        marker_id = name or f"marker-{len(self._layers)}"

        self.call_js_method(
            "addMarker",
            lng,
            lat,
            id=marker_id,
            popup=popup,
            tooltip=tooltip,
            color=color,
            draggable=draggable,
            scale=scale,
            popupMaxWidth=popup_max_width,
            tooltipMaxWidth=tooltip_max_width,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            marker_id: {
                "id": marker_id,
                "type": "marker",
                "lngLat": [lng, lat],
            },
        }
        self._add_to_layer_dict(marker_id, "Markers")
        return marker_id

    def add_markers(
        self,
        data: Any,
        lng_column: Optional[str] = None,
        lat_column: Optional[str] = None,
        popup_column: Optional[str] = None,
        tooltip_column: Optional[str] = None,
        color: str = "#3388ff",
        scale: float = 1.0,
        popup_max_width: str = "240px",
        tooltip_max_width: str = "240px",
        draggable: bool = False,
        name: Optional[str] = None,
        **kwargs,
    ) -> str:
        """Add multiple markers from data.

        Args:
            data: Data source - can be:
                - List of dicts with 'lng'/'lon'/'longitude' and 'lat'/'latitude' keys
                - GeoDataFrame with Point geometries
                - GeoJSON FeatureCollection with Point features
            lng_column: Column name for longitude (auto-detected if None).
            lat_column: Column name for latitude (auto-detected if None).
            popup_column: Column name for popup content (shown on click).
            tooltip_column: Column name for tooltip content (shown on hover).
            color: Marker color as hex string.
            scale: Marker size multiplier (default 1.0, range 0.1 to 3.0).
            popup_max_width: Maximum width of popup (CSS value, default "240px").
            tooltip_max_width: Maximum width of tooltip (CSS value, default "240px").
            draggable: Whether markers can be dragged.
            name: Layer identifier. If None, auto-generated.
            **kwargs: Additional marker options.

        Returns:
            The layer identifier.

        Example:
            >>> from anymap_ts import Map
            >>> m = Map()
            >>> cities = [
            ...     {"name": "SF", "info": "San Francisco", "lng": -122.4, "lat": 37.8},
            ...     {"name": "NYC", "info": "New York City", "lng": -74.0, "lat": 40.7},
            ... ]
            >>> m.add_markers(cities, popup_column="name", tooltip_column="info", scale=1.5)
        """
        layer_id = name or f"markers-{len(self._layers)}"
        markers = []

        # Handle GeoDataFrame
        if hasattr(data, "geometry"):
            for _, row in data.iterrows():
                geom = row.geometry
                if geom.geom_type == "Point":
                    marker = {"lngLat": [geom.x, geom.y]}
                    if popup_column and popup_column in row:
                        marker["popup"] = str(row[popup_column])
                    if tooltip_column and tooltip_column in row:
                        marker["tooltip"] = str(row[tooltip_column])
                    markers.append(marker)
        # Handle GeoJSON
        elif isinstance(data, dict) and data.get("type") == "FeatureCollection":
            for feature in data.get("features", []):
                geom = feature.get("geometry", {})
                if geom.get("type") == "Point":
                    coords = geom.get("coordinates", [])
                    marker = {"lngLat": coords[:2]}
                    props = feature.get("properties", {})
                    if popup_column and popup_column in props:
                        marker["popup"] = str(props[popup_column])
                    if tooltip_column and tooltip_column in props:
                        marker["tooltip"] = str(props[tooltip_column])
                    markers.append(marker)
        # Handle list of dicts
        elif isinstance(data, list):
            lng_keys = ["lng", "lon", "longitude", "x"]
            lat_keys = ["lat", "latitude", "y"]

            for item in data:
                if not isinstance(item, dict):
                    continue

                # Find lng/lat values
                lng_val = None
                lat_val = None

                if lng_column and lng_column in item:
                    lng_val = item[lng_column]
                else:
                    for key in lng_keys:
                        if key in item:
                            lng_val = item[key]
                            break

                if lat_column and lat_column in item:
                    lat_val = item[lat_column]
                else:
                    for key in lat_keys:
                        if key in item:
                            lat_val = item[key]
                            break

                if lng_val is not None and lat_val is not None:
                    marker = {"lngLat": [float(lng_val), float(lat_val)]}
                    if popup_column and popup_column in item:
                        marker["popup"] = str(item[popup_column])
                    if tooltip_column and tooltip_column in item:
                        marker["tooltip"] = str(item[tooltip_column])
                    markers.append(marker)

        if not markers:
            raise ValueError("No valid point data found in input")

        self.call_js_method(
            "addMarkers",
            id=layer_id,
            markers=markers,
            color=color,
            scale=scale,
            popupMaxWidth=popup_max_width,
            tooltipMaxWidth=tooltip_max_width,
            draggable=draggable,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "markers",
                "count": len(markers),
            },
        }
        self._add_to_layer_dict(layer_id, "Markers")
        return layer_id

    def remove_marker(self, marker_id: str) -> None:
        """Remove a marker from the map.

        Args:
            marker_id: Marker identifier to remove.
        """
        self._remove_layer_internal(marker_id, "removeMarker")

    # -------------------------------------------------------------------------
    # Heatmap Methods
    # -------------------------------------------------------------------------

    def add_heatmap(
        self,
        data: Any,
        weight_property: Optional[str] = None,
        radius: int = 20,
        intensity: float = 1.0,
        colormap: Optional[List] = None,
        opacity: float = 0.8,
        name: Optional[str] = None,
        fit_bounds: bool = True,
        **kwargs,
    ) -> None:
        """Add a heatmap layer to the map.

        Creates a heatmap visualization from point data using MapLibre's
        native heatmap layer type.

        Args:
            data: Point data - can be GeoJSON, GeoDataFrame, or file path.
            weight_property: Property name to use for point weights.
                If None, all points have equal weight.
            radius: Radius of influence for each point in pixels.
            intensity: Intensity multiplier for the heatmap.
            colormap: Color gradient as list of [stop, color] pairs.
                Example: [[0, "blue"], [0.5, "yellow"], [1, "red"]]
                Default: blue-yellow-red gradient.
            opacity: Layer opacity (0-1).
            name: Layer identifier. If None, auto-generated.
            fit_bounds: Whether to fit map to data bounds.
            **kwargs: Additional heatmap layer options.

        Example:
            >>> from anymap_ts import Map
            >>> m = Map()
            >>> m.add_heatmap(
            ...     "earthquakes.geojson",
            ...     weight_property="magnitude",
            ...     radius=30,
            ...     colormap=[[0, "blue"], [0.5, "lime"], [1, "red"]]
            ... )
        """
        self._validate_opacity(opacity)
        layer_id = name or f"heatmap-{len(self._layers)}"

        # Convert data to GeoJSON
        geojson = to_geojson(data)

        # Handle URL data - fetch GeoJSON
        if geojson.get("type") == "url":
            url = geojson["url"]
            geojson = fetch_geojson(url)

        # Default colormap
        if colormap is None:
            colormap = [
                [0, "rgba(33,102,172,0)"],
                [0.2, "rgb(103,169,207)"],
                [0.4, "rgb(209,229,240)"],
                [0.6, "rgb(253,219,199)"],
                [0.8, "rgb(239,138,98)"],
                [1, "rgb(178,24,43)"],
            ]

        # Build heatmap paint properties
        paint = {
            "heatmap-radius": radius,
            "heatmap-intensity": intensity,
            "heatmap-opacity": opacity,
            "heatmap-color": [
                "interpolate",
                ["linear"],
                ["heatmap-density"],
            ],
        }

        # Add colormap stops
        for stop, color in colormap:
            paint["heatmap-color"].extend([stop, color])

        # Add weight if specified
        if weight_property:
            paint["heatmap-weight"] = ["get", weight_property]

        # Get bounds
        bounds = get_bounds(geojson) if fit_bounds else None

        self.call_js_method(
            "addGeoJSON",
            data=geojson,
            name=layer_id,
            layerType="heatmap",
            paint=paint,
            fitBounds=fit_bounds,
            bounds=bounds,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "heatmap",
                "source": f"{layer_id}-source",
                "paint": paint,
            },
        }
        self._add_to_layer_dict(layer_id, "Heatmap")

    # -------------------------------------------------------------------------
    # Raster Data Methods
    # -------------------------------------------------------------------------

    def add_raster(
        self,
        source: str,
        name: Optional[str] = None,
        attribution: str = "",
        indexes: Optional[List[int]] = None,
        colormap: Optional[str] = None,
        vmin: Optional[float] = None,
        vmax: Optional[float] = None,
        nodata: Optional[float] = None,
        fit_bounds: bool = True,
        **kwargs,
    ) -> None:
        """Add a raster layer from a local file using localtileserver.

        Args:
            source: Path to local raster file
            name: Layer name
            attribution: Attribution text
            indexes: Band indexes to use
            colormap: Colormap name
            vmin: Minimum value for colormap
            vmax: Maximum value for colormap
            nodata: NoData value
            fit_bounds: Whether to fit map to raster bounds
            **kwargs: Additional options
        """
        try:
            from localtileserver import TileClient
        except ImportError:
            raise ImportError(
                "localtileserver is required for local raster support. "
                "Install with: pip install anymap-ts[raster]"
            )

        client = TileClient(source)

        # Build parameters dict and pass all at once
        tile_params = {}
        if indexes:
            tile_params["indexes"] = indexes
        if colormap:
            tile_params["colormap"] = colormap
        if vmin is not None or vmax is not None:
            tile_params["vmin"] = vmin if vmin is not None else client.min
            tile_params["vmax"] = vmax if vmax is not None else client.max
        if nodata is not None:
            tile_params["nodata"] = nodata

        tile_url = client.get_tile_url(**tile_params)

        layer_name = name or Path(source).stem

        self.add_tile_layer(
            tile_url,
            name=layer_name,
            attribution=attribution,
            **kwargs,
        )

        # Fit bounds if requested
        if fit_bounds:
            bounds = client.bounds()
            if bounds:
                self.fit_bounds([bounds[0], bounds[1], bounds[2], bounds[3]])

    def add_tile_layer(
        self,
        url: str,
        name: Optional[str] = None,
        attribution: str = "",
        min_zoom: int = 0,
        max_zoom: int = 22,
        **kwargs,
    ) -> None:
        """Add an XYZ tile layer.

        Args:
            url: Tile URL template with {x}, {y}, {z} placeholders
            name: Layer name
            attribution: Attribution text
            min_zoom: Minimum zoom level
            max_zoom: Maximum zoom level
            **kwargs: Additional options
        """
        layer_id = name or f"tiles-{len(self._layers)}"

        self.call_js_method(
            "addTileLayer",
            url,
            name=layer_id,
            attribution=attribution,
            minZoom=min_zoom,
            maxZoom=max_zoom,
            **kwargs,
        )

        # Track layer
        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "raster",
                "source": f"{layer_id}-source",
            },
        }
        self._add_to_layer_dict(layer_id, "Raster")

    def add_stac_layer(
        self,
        url: Optional[str] = None,
        item: Optional[Any] = None,
        assets: Optional[List[str]] = None,
        colormap: Optional[str] = None,
        rescale: Optional[List[float]] = None,
        opacity: float = 1.0,
        layer_id: Optional[str] = None,
        titiler_endpoint: str = "https://titiler.xyz",
        attribution: str = "STAC",
        fit_bounds: bool = True,
        **kwargs,
    ) -> None:
        """Add a STAC (SpatioTemporal Asset Catalog) layer to the map.

        Uses TiTiler to render STAC items as XYZ tiles on the map.
        Supports both STAC item URLs and pystac Item objects.

        Args:
            url: URL to a STAC item JSON
            item: A pystac Item object
            assets: List of asset names/bands to visualize
            colormap: Colormap name (e.g., 'viridis', 'plasma', 'inferno')
            rescale: Min/max values for rescaling as [min, max]
            opacity: Layer opacity (0-1)
            layer_id: Custom layer identifier
            titiler_endpoint: TiTiler server endpoint URL
            attribution: Attribution text for the layer
            fit_bounds: Whether to fit map to STAC item bounds
            **kwargs: Additional tile layer options

        Example:
            >>> from anymap_ts import Map
            >>> m = Map()
            >>> # From URL
            >>> m.add_stac_layer(
            ...     url="https://planetarycomputer.microsoft.com/api/stac/v1/collections/sentinel-2-l2a/items/S2A_MSIL2A_20220101T181901_N0301_R027_T10TEM_20220101T201906",
            ...     assets=["red", "green", "blue"],
            ...     rescale=[0, 3000]
            ... )
            >>> # From pystac Item
            >>> import pystac
            >>> item = pystac.Item.from_file("path/to/item.json")
            >>> m.add_stac_layer(item=item, assets=["nir", "red"], colormap="ndvi")
        """
        if url is None and item is None:
            raise ValueError("Either 'url' or 'item' must be provided")

        if url is not None and item is not None:
            raise ValueError("Provide either 'url' or 'item', not both")

        # Handle pystac Item object
        if item is not None:
            try:
                # Check if it's a pystac Item
                if hasattr(item, "to_dict") and hasattr(item, "self_href"):
                    stac_url = item.self_href
                    if not stac_url:
                        # Try to get URL from item properties if no self_href
                        if hasattr(item, "links"):
                            for link in item.links:
                                if link.rel == "self":
                                    stac_url = link.href
                                    break
                        if not stac_url:
                            raise ValueError(
                                "STAC item must have a self_href or self link for tile generation"
                            )
                else:
                    raise ValueError(
                        "Item must be a pystac Item object with to_dict() and self_href attributes"
                    )
            except Exception as e:
                raise ValueError(f"Invalid STAC item: {e}")
        else:
            stac_url = url

        # Build TiTiler tile URL
        tile_params = {"url": stac_url}

        if assets:
            tile_params["assets"] = ",".join(assets)
        if colormap:
            tile_params["colormap_name"] = colormap
        if rescale:
            if len(rescale) == 2:
                tile_params["rescale"] = f"{rescale[0]},{rescale[1]}"
            else:
                raise ValueError("rescale must be a list of two values [min, max]")

        # Construct tile URL template
        query_string = urlencode(tile_params)
        tile_url = f"{titiler_endpoint.rstrip('/')}/stac/tiles/{{z}}/{{x}}/{{y}}?{query_string}"

        layer_name = layer_id or f"stac-{len(self._layers)}"

        # Add as tile layer
        self.add_tile_layer(
            url=tile_url,
            name=layer_name,
            attribution=attribution,
            **kwargs,
        )

        # Update layer info to mark as STAC
        if layer_name in self._layers:
            self._layers[layer_name].update(
                {
                    "stac_url": stac_url,
                    "stac_assets": assets,
                    "colormap": colormap,
                    "rescale": rescale,
                }
            )

        # Try to fit bounds if requested and we have an item object
        if fit_bounds and item is not None:
            try:
                bbox = item.bbox
                if bbox and len(bbox) == 4:
                    self.fit_bounds([[bbox[0], bbox[1]], [bbox[2], bbox[3]]])
            except Exception:
                pass  # Skip bounds fitting if bbox is not available

    # -------------------------------------------------------------------------
    # COG Layer (deck.gl)
    # -------------------------------------------------------------------------

    def add_cog_layer(
        self,
        url: str,
        name: Optional[str] = None,
        opacity: float = 1.0,
        visible: bool = True,
        debug: bool = False,
        debug_opacity: float = 0.25,
        max_error: float = 0.125,
        fit_bounds: bool = True,
        before_id: Optional[str] = None,
        **kwargs,
    ) -> None:
        """Add a Cloud Optimized GeoTIFF (COG) layer using @developmentseed/deck.gl-geotiff.

        This method renders COG files directly in the browser using GPU-accelerated
        deck.gl-geotiff rendering with automatic reprojection support.

        Args:
            url: URL to the Cloud Optimized GeoTIFF file.
            name: Layer ID. If None, auto-generated.
            opacity: Layer opacity (0-1).
            visible: Whether layer is visible.
            debug: Show reprojection mesh for debugging.
            debug_opacity: Opacity of debug mesh (0-1).
            max_error: Maximum reprojection error in pixels. Lower values
                create denser mesh for better accuracy.
            fit_bounds: Whether to fit map to COG bounds after loading.
            before_id: ID of layer to insert before.
            **kwargs: Additional COGLayer props.

        Example:
            >>> from anymap_ts import Map
            >>> m = Map()
            >>> m.add_cog_layer(
            ...     "https://example.com/landcover.tif",
            ...     name="landcover",
            ...     opacity=0.8
            ... )
        """
        layer_id = name or f"cog-{len(self._layers)}"

        self.call_js_method(
            "addCOGLayer",
            id=layer_id,
            geotiff=url,
            opacity=opacity,
            visible=visible,
            debug=debug,
            debugOpacity=debug_opacity,
            maxError=max_error,
            fitBounds=fit_bounds,
            beforeId=before_id,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "cog",
                "url": url,
            },
        }
        self._add_to_layer_dict(layer_id, "Raster")

    def remove_cog_layer(self, layer_id: str) -> None:
        """Remove a COG layer.

        Args:
            layer_id: Layer identifier to remove.
        """
        self._remove_layer_internal(layer_id, "removeCOGLayer")

    # -------------------------------------------------------------------------
    # Zarr Layer (@carbonplan/zarr-layer)
    # -------------------------------------------------------------------------

    def add_zarr_layer(
        self,
        url: str,
        variable: str,
        name: Optional[str] = None,
        colormap: Optional[List[str]] = None,
        clim: Optional[Tuple[float, float]] = None,
        opacity: float = 1.0,
        selector: Optional[Dict[str, Any]] = None,
        minzoom: int = 0,
        maxzoom: int = 22,
        fill_value: Optional[float] = None,
        spatial_dimensions: Optional[Dict[str, str]] = None,
        zarr_version: Optional[int] = None,
        bounds: Optional[List[float]] = None,
        **kwargs,
    ) -> None:
        """Add a Zarr dataset layer for visualizing multidimensional array data.

        This method renders Zarr pyramid datasets directly in the browser using
        GPU-accelerated WebGL rendering via @carbonplan/zarr-layer.

        Args:
            url: URL to the Zarr store (pyramid format recommended).
            variable: Variable name in the Zarr dataset to visualize.
            name: Layer ID. If None, auto-generated.
            colormap: List of hex color strings for visualization.
                Example: ['#0000ff', '#ffff00', '#ff0000'] (blue-yellow-red).
                Default: ['#000000', '#ffffff'] (black to white).
            clim: Color range as (min, max) tuple.
                Default: (0, 100).
            opacity: Layer opacity (0-1).
            selector: Dimension selector for multi-dimensional data.
                Example: {"month": 4} to select 4th month.
            minzoom: Minimum zoom level for rendering.
            maxzoom: Maximum zoom level for rendering.
            fill_value: No-data value (auto-detected from metadata if not set).
            spatial_dimensions: Custom spatial dimension names.
                Example: {"lat": "y", "lon": "x"} for non-standard names.
            zarr_version: Zarr format version (2 or 3). Auto-detected if not set.
            bounds: Explicit spatial bounds [xMin, yMin, xMax, yMax].
                Units depend on CRS: degrees for EPSG:4326, meters for EPSG:3857.
            **kwargs: Additional ZarrLayer props.

        Example:
            >>> from anymap_ts import Map
            >>> m = Map()
            >>> m.add_zarr_layer(
            ...     "https://example.com/climate.zarr",
            ...     variable="temperature",
            ...     clim=(270, 310),
            ...     colormap=['#0000ff', '#ffff00', '#ff0000'],
            ...     selector={"month": 7}
            ... )
        """
        layer_id = name or f"zarr-{len(self._layers)}"

        self.call_js_method(
            "addZarrLayer",
            id=layer_id,
            source=url,
            variable=variable,
            colormap=colormap or ["#000000", "#ffffff"],
            clim=list(clim) if clim else [0, 100],
            opacity=opacity,
            selector=selector or {},
            minzoom=minzoom,
            maxzoom=maxzoom,
            fillValue=fill_value,
            spatialDimensions=spatial_dimensions,
            zarrVersion=zarr_version,
            bounds=bounds,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "zarr",
                "url": url,
                "variable": variable,
            },
        }
        self._add_to_layer_dict(layer_id, "Raster")

    def remove_zarr_layer(self, layer_id: str) -> None:
        """Remove a Zarr layer.

        Args:
            layer_id: Layer identifier to remove.
        """
        self._remove_layer_internal(layer_id, "removeZarrLayer")

    def update_zarr_layer(
        self,
        layer_id: str,
        selector: Optional[Dict[str, Any]] = None,
        clim: Optional[Tuple[float, float]] = None,
        colormap: Optional[List[str]] = None,
        opacity: Optional[float] = None,
    ) -> None:
        """Update a Zarr layer's properties dynamically.

        Args:
            layer_id: Layer identifier.
            selector: New dimension selector.
            clim: New color range.
            colormap: New colormap.
            opacity: New opacity value (0-1).
        """
        update_kwargs: Dict[str, Any] = {"id": layer_id}
        if selector is not None:
            update_kwargs["selector"] = selector
        if clim is not None:
            update_kwargs["clim"] = list(clim)
        if colormap is not None:
            update_kwargs["colormap"] = colormap
        if opacity is not None:
            update_kwargs["opacity"] = opacity
        self.call_js_method("updateZarrLayer", **update_kwargs)

    # -------------------------------------------------------------------------
    # PMTiles Layer
    # -------------------------------------------------------------------------

    def add_pmtiles_layer(
        self,
        url: str,
        layer_id: Optional[str] = None,
        style: Optional[Dict[str, Any]] = None,
        opacity: float = 1.0,
        visible: bool = True,
        fit_bounds: bool = False,
        source_type: str = "vector",
        **kwargs,
    ) -> None:
        """Add a PMTiles layer for efficient vector or raster tile serving.

        PMTiles is a single-file archive format for pyramids of map tiles.
        It enables efficient web-native map serving without requiring a
        separate tile server infrastructure.

        Args:
            url: URL to the PMTiles file (e.g., "https://example.com/data.pmtiles").
            layer_id: Layer identifier. If None, auto-generated.
            style: Layer style configuration for vector tiles.
                For vector PMTiles, can include:
                - type: Layer type ('fill', 'line', 'circle', 'symbol')
                - source-layer: Source layer name from vector tiles
                - paint properties (e.g., 'fill-color', 'line-width')
                - layout properties (e.g., 'visibility')
                Example: {"type": "line", "source-layer": "roads", "line-color": "#ff0000"}
            opacity: Layer opacity (0-1).
            visible: Whether layer is initially visible.
            fit_bounds: Whether to fit map to layer bounds after loading.
            source_type: Source type - "vector" for vector PMTiles, "raster" for raster PMTiles.
            **kwargs: Additional layer options.

        Example:
            >>> from anymap_ts import Map
            >>> m = Map()
            >>> # Add vector PMTiles
            >>> m.add_pmtiles_layer(
            ...     url="https://example.com/countries.pmtiles",
            ...     layer_id="countries",
            ...     style={
            ...         "type": "fill",
            ...         "source-layer": "countries",
            ...         "fill-color": "#3388ff",
            ...         "fill-opacity": 0.6
            ...     }
            ... )
            >>> # Add raster PMTiles
            >>> m.add_pmtiles_layer(
            ...     url="https://example.com/satellite.pmtiles",
            ...     layer_id="satellite",
            ...     source_type="raster",
            ...     opacity=0.8
            ... )
        """
        layer_id = layer_id or f"pmtiles-{len(self._layers)}"

        self.call_js_method(
            "addPMTilesLayer",
            url=url,
            id=layer_id,
            style=style or {},
            opacity=opacity,
            visible=visible,
            fitBounds=fit_bounds,
            sourceType=source_type,
            name=layer_id,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "pmtiles",
                "url": url,
                "source_type": source_type,
            },
        }
        category = "Vector" if source_type == "vector" else "Raster"
        self._add_to_layer_dict(layer_id, category)

    def remove_pmtiles_layer(self, layer_id: str) -> None:
        """Remove a PMTiles layer.

        Args:
            layer_id: Layer identifier to remove.
        """
        self._remove_layer_internal(layer_id, "removePMTilesLayer")

    # -------------------------------------------------------------------------
    # Arc Layer (deck.gl)
    # -------------------------------------------------------------------------

    def add_arc_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_source_position: Union[str, Any] = "source",
        get_target_position: Union[str, Any] = "target",
        get_source_color: Optional[List[int]] = None,
        get_target_color: Optional[List[int]] = None,
        get_width: Union[float, str] = 1,
        get_height: float = 1,
        great_circle: bool = False,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add an arc layer for origin-destination visualization using deck.gl.

        Arc layers are ideal for visualizing connections between locations,
        such as flight routes, migration patterns, or network flows.

        Args:
            data: Array of data objects with source/target coordinates.
                Each object should have source and target positions.
            name: Layer ID. If None, auto-generated.
            get_source_position: Accessor for source position [lng, lat].
                Can be a string (property name) or a value.
            get_target_position: Accessor for target position [lng, lat].
                Can be a string (property name) or a value.
            get_source_color: Source end color as [r, g, b, a].
                Default: [51, 136, 255, 255] (blue).
            get_target_color: Target end color as [r, g, b, a].
                Default: [255, 136, 51, 255] (orange).
            get_width: Arc width in pixels. Can be a number or accessor.
            get_height: Arc height multiplier. Higher values create more curved arcs.
            great_circle: Whether to draw arcs along great circles.
            pickable: Whether layer responds to hover/click events.
            opacity: Layer opacity (0-1).
            **kwargs: Additional ArcLayer props.

        Example:
            >>> from anymap_ts import MapLibreMap
            >>> m = MapLibreMap()
            >>> arcs = [
            ...     {"source": [-122.4, 37.8], "target": [-73.9, 40.7]},
            ...     {"source": [-122.4, 37.8], "target": [-0.1, 51.5]},
            ... ]
            >>> m.add_arc_layer(arcs, name="flights")
        """
        layer_id = name or f"arc-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addArcLayer",
            id=layer_id,
            data=processed_data,
            getSourcePosition=get_source_position,
            getTargetPosition=get_target_position,
            getSourceColor=get_source_color or [51, 136, 255, 255],
            getTargetColor=get_target_color or [255, 136, 51, 255],
            getWidth=get_width,
            getHeight=get_height,
            greatCircle=great_circle,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "arc",
            },
        }
        self._add_to_layer_dict(layer_id, "Deck.gl")

    def remove_arc_layer(self, layer_id: str) -> None:
        """Remove an arc layer.

        Args:
            layer_id: Layer identifier to remove.
        """
        self._remove_layer_internal(layer_id, "removeArcLayer")

    # -------------------------------------------------------------------------
    # PointCloud Layer (deck.gl)
    # -------------------------------------------------------------------------

    def add_point_cloud_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_position: Union[str, Any] = "position",
        get_color: Optional[Union[List[int], str]] = None,
        get_normal: Optional[Union[str, Any]] = None,
        point_size: float = 2,
        size_units: str = "pixels",
        pickable: bool = True,
        opacity: float = 1.0,
        material: bool = True,
        coordinate_system: Optional[int] = None,
        coordinate_origin: Optional[List[float]] = None,
        **kwargs,
    ) -> None:
        """Add a point cloud layer for 3D point visualization using deck.gl.

        Point cloud layers render large collections of 3D points, ideal for
        LiDAR data, photogrammetry outputs, or any 3D point dataset.

        Args:
            data: Array of point data with positions. Each point should have
                x, y, z coordinates (or position array).
            name: Layer ID. If None, auto-generated.
            get_position: Accessor for point position [x, y, z].
                Can be a string (property name) or a value.
            get_color: Accessor or value for point color [r, g, b, a].
                Default: [255, 255, 255, 255] (white).
            get_normal: Accessor for point normal [nx, ny, nz] for lighting.
                Default: [0, 0, 1] (pointing up).
            point_size: Point size in pixels or meters (depends on size_units).
            size_units: Size units: 'pixels', 'meters', or 'common'.
            pickable: Whether layer responds to hover/click events.
            opacity: Layer opacity (0-1).
            material: Whether to enable lighting effects.
            coordinate_system: Coordinate system for positions.
            coordinate_origin: Origin for coordinate system [x, y, z].
            **kwargs: Additional PointCloudLayer props.

        Example:
            >>> from anymap_ts import MapLibreMap
            >>> import numpy as np
            >>> m = MapLibreMap(pitch=45)
            >>> points = [
            ...     {"position": [-122.4, 37.8, 100], "color": [255, 0, 0, 255]},
            ...     {"position": [-122.3, 37.7, 200], "color": [0, 255, 0, 255]},
            ... ]
            >>> m.add_point_cloud_layer(points, point_size=5)
        """
        layer_id = name or f"pointcloud-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addPointCloudLayer",
            id=layer_id,
            data=processed_data,
            getPosition=get_position,
            getColor=get_color or [255, 255, 255, 255],
            getNormal=get_normal,
            pointSize=point_size,
            sizeUnits=size_units,
            pickable=pickable,
            opacity=opacity,
            material=material,
            coordinateSystem=coordinate_system,
            coordinateOrigin=coordinate_origin,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "pointcloud",
            },
        }
        self._add_to_layer_dict(layer_id, "Deck.gl")

    def remove_point_cloud_layer(self, layer_id: str) -> None:
        """Remove a point cloud layer.

        Args:
            layer_id: Layer identifier to remove.
        """
        self._remove_layer_internal(layer_id, "removePointCloudLayer")

    # -------------------------------------------------------------------------
    # Scatterplot Layer (deck.gl)
    # -------------------------------------------------------------------------

    def add_scatterplot_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_position: Union[str, Any] = "coordinates",
        get_radius: Union[float, str] = 5,
        get_fill_color: Optional[Union[List[int], str]] = None,
        get_line_color: Optional[Union[List[int], str]] = None,
        radius_scale: float = 1,
        radius_min_pixels: float = 1,
        radius_max_pixels: float = 100,
        line_width_min_pixels: float = 1,
        stroked: bool = True,
        filled: bool = True,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add a scatterplot layer for sized/colored point visualization using deck.gl.

        Scatterplot layers render circles at given coordinates with configurable
        radius and color, ideal for point datasets where size and color encode data.

        Args:
            data: Array of data objects or GeoJSON with point coordinates.
            name: Layer ID. If None, auto-generated.
            get_position: Accessor for point position [lng, lat].
                Can be a string (property name) or a value.
            get_radius: Accessor for point radius in meters.
            get_fill_color: Accessor for fill color [r, g, b, a].
                Default: [51, 136, 255, 200] (blue).
            get_line_color: Accessor for stroke color [r, g, b, a].
                Default: [255, 255, 255, 255] (white).
            radius_scale: Global radius multiplier.
            radius_min_pixels: Minimum radius in pixels.
            radius_max_pixels: Maximum radius in pixels.
            line_width_min_pixels: Minimum stroke width in pixels.
            stroked: Whether to draw stroke around points.
            filled: Whether to fill points.
            pickable: Whether layer responds to hover/click events.
            opacity: Layer opacity (0-1).
            **kwargs: Additional ScatterplotLayer props.

        Example:
            >>> from anymap_ts import MapLibreMap
            >>> m = MapLibreMap()
            >>> points = [
            ...     {"coordinates": [-122.4, 37.8], "size": 100},
            ...     {"coordinates": [-122.5, 37.7], "size": 200},
            ... ]
            >>> m.add_scatterplot_layer(points, get_radius="size")
        """
        layer_id = name or f"scatterplot-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addScatterplotLayer",
            id=layer_id,
            data=processed_data,
            getPosition=get_position,
            getRadius=get_radius,
            getFillColor=get_fill_color or [51, 136, 255, 200],
            getLineColor=get_line_color or [255, 255, 255, 255],
            radiusScale=radius_scale,
            radiusMinPixels=radius_min_pixels,
            radiusMaxPixels=radius_max_pixels,
            lineWidthMinPixels=line_width_min_pixels,
            stroked=stroked,
            filled=filled,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "scatterplot",
            },
        }
        self._add_to_layer_dict(layer_id, "Deck.gl")

    # -------------------------------------------------------------------------
    # Path Layer (deck.gl)
    # -------------------------------------------------------------------------

    def add_path_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_path: Union[str, Any] = "path",
        get_color: Optional[Union[List[int], str]] = None,
        get_width: Union[float, str] = 1,
        width_scale: float = 1,
        width_min_pixels: float = 1,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add a path layer for route/trajectory rendering using deck.gl.

        Path layers render polylines defined by arrays of coordinates,
        ideal for visualizing routes, trajectories, or any line-based data.

        Args:
            data: Array of data objects with path coordinates.
            name: Layer ID. If None, auto-generated.
            get_path: Accessor for path coordinates [[lng, lat], ...].
                Can be a string (property name) or a value.
            get_color: Accessor for path color [r, g, b, a].
                Default: [51, 136, 255, 200] (blue).
            get_width: Accessor for path width in meters.
            width_scale: Global width multiplier.
            width_min_pixels: Minimum width in pixels.
            pickable: Whether layer responds to hover/click events.
            opacity: Layer opacity (0-1).
            **kwargs: Additional PathLayer props.

        Example:
            >>> from anymap_ts import MapLibreMap
            >>> m = MapLibreMap()
            >>> routes = [
            ...     {"path": [[-122.4, 37.8], [-122.5, 37.7], [-122.6, 37.8]]},
            ... ]
            >>> m.add_path_layer(routes, get_color=[255, 0, 0], get_width=3)
        """
        layer_id = name or f"path-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addPathLayer",
            id=layer_id,
            data=processed_data,
            getPath=get_path,
            getColor=get_color or [51, 136, 255, 200],
            getWidth=get_width,
            widthScale=width_scale,
            widthMinPixels=width_min_pixels,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "path",
            },
        }
        self._add_to_layer_dict(layer_id, "Deck.gl")

    # -------------------------------------------------------------------------
    # Polygon Layer (deck.gl)
    # -------------------------------------------------------------------------

    def add_polygon_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_polygon: Union[str, Any] = "polygon",
        get_fill_color: Optional[Union[List[int], str]] = None,
        get_line_color: Optional[Union[List[int], str]] = None,
        get_line_width: Union[float, str] = 1,
        get_elevation: Union[float, str] = 0,
        extruded: bool = False,
        wireframe: bool = False,
        filled: bool = True,
        stroked: bool = True,
        line_width_min_pixels: float = 1,
        pickable: bool = True,
        opacity: float = 0.5,
        **kwargs,
    ) -> None:
        """Add a polygon layer for filled polygon visualization using deck.gl.

        Polygon layers render filled and/or stroked polygons with optional
        3D extrusion, ideal for choropleth maps and area visualizations.

        Args:
            data: Array of data objects with polygon coordinates.
            name: Layer ID. If None, auto-generated.
            get_polygon: Accessor for polygon coordinates.
                Can be a string (property name) or a value.
            get_fill_color: Accessor for fill color [r, g, b, a].
                Default: [51, 136, 255, 128].
            get_line_color: Accessor for stroke color [r, g, b, a].
                Default: [0, 0, 255, 255].
            get_line_width: Accessor for stroke width.
            get_elevation: Accessor for 3D extrusion height.
            extruded: Whether to render as 3D polygons.
            wireframe: Whether to render wireframe (extruded only).
            filled: Whether to fill polygons.
            stroked: Whether to draw stroke.
            line_width_min_pixels: Minimum stroke width in pixels.
            pickable: Whether layer responds to hover/click events.
            opacity: Layer opacity (0-1).
            **kwargs: Additional PolygonLayer props.

        Example:
            >>> from anymap_ts import MapLibreMap
            >>> m = MapLibreMap(pitch=45)
            >>> polygons = [
            ...     {"polygon": [[-122.4, 37.8], [-122.5, 37.7], [-122.3, 37.7]], "height": 1000},
            ... ]
            >>> m.add_polygon_layer(polygons, extruded=True, get_elevation="height")
        """
        layer_id = name or f"polygon-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addPolygonLayer",
            id=layer_id,
            data=processed_data,
            getPolygon=get_polygon,
            getFillColor=get_fill_color or [51, 136, 255, 128],
            getLineColor=get_line_color or [0, 0, 255, 255],
            getLineWidth=get_line_width,
            getElevation=get_elevation,
            extruded=extruded,
            wireframe=wireframe,
            filled=filled,
            stroked=stroked,
            lineWidthMinPixels=line_width_min_pixels,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "polygon",
            },
        }
        self._add_to_layer_dict(layer_id, "Deck.gl")

    # -------------------------------------------------------------------------
    # Hexagon Layer (deck.gl)
    # -------------------------------------------------------------------------

    def add_hexagon_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_position: Union[str, Any] = "coordinates",
        radius: float = 1000,
        elevation_scale: float = 4,
        extruded: bool = True,
        color_range: Optional[List[List[int]]] = None,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add a hexagon layer for hexagonal binning/aggregation using deck.gl.

        Hexagon layers aggregate points into hexagonal bins and render them
        with height and color based on point density.

        Args:
            data: Array of data objects with position coordinates.
            name: Layer ID. If None, auto-generated.
            get_position: Accessor for point position [lng, lat].
            radius: Hexagon radius in meters.
            elevation_scale: Elevation multiplier for 3D hexagons.
            extruded: Whether to render as 3D hexagons.
            color_range: Color gradient for aggregation [[r, g, b], ...].
            pickable: Whether layer responds to hover/click events.
            opacity: Layer opacity (0-1).
            **kwargs: Additional HexagonLayer props.

        Example:
            >>> from anymap_ts import MapLibreMap
            >>> m = MapLibreMap(pitch=45)
            >>> points = [
            ...     {"coordinates": [-122.4, 37.8]},
            ...     {"coordinates": [-122.41, 37.81]},
            ... ]
            >>> m.add_hexagon_layer(points, radius=500, elevation_scale=10)
        """
        layer_id = name or f"hexagon-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        default_color_range = [
            [1, 152, 189],
            [73, 227, 206],
            [216, 254, 181],
            [254, 237, 177],
            [254, 173, 84],
            [209, 55, 78],
        ]

        self.call_js_method(
            "addHexagonLayer",
            id=layer_id,
            data=processed_data,
            getPosition=get_position,
            radius=radius,
            elevationScale=elevation_scale,
            extruded=extruded,
            colorRange=color_range or default_color_range,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "hexagon",
            },
        }
        self._add_to_layer_dict(layer_id, "Deck.gl")

    # -------------------------------------------------------------------------
    # Deck.gl Heatmap Layer
    # -------------------------------------------------------------------------

    def add_deck_heatmap_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_position: Union[str, Any] = "coordinates",
        get_weight: Union[float, str] = 1,
        radius_pixels: float = 30,
        intensity: float = 1,
        threshold: float = 0.05,
        color_range: Optional[List[List[int]]] = None,
        opacity: float = 1,
        **kwargs,
    ) -> None:
        """Add a GPU-accelerated heatmap layer using deck.gl.

        This is an alternative to the native MapLibre heatmap layer, using
        deck.gl's GPU-based rendering for better performance with large datasets.

        Args:
            data: Array of data objects with position coordinates.
            name: Layer ID. If None, auto-generated.
            get_position: Accessor for point position [lng, lat].
            get_weight: Accessor for point weight value.
            radius_pixels: Influence radius in pixels.
            intensity: Intensity multiplier.
            threshold: Minimum density threshold (0-1).
            color_range: Color gradient [[r, g, b, a], ...].
            opacity: Layer opacity (0-1).
            **kwargs: Additional HeatmapLayer props.

        Example:
            >>> from anymap_ts import MapLibreMap
            >>> m = MapLibreMap()
            >>> points = [
            ...     {"coordinates": [-122.4, 37.8], "weight": 5},
            ...     {"coordinates": [-122.5, 37.7], "weight": 10},
            ... ]
            >>> m.add_deck_heatmap_layer(points, get_weight="weight")
        """
        layer_id = name or f"deck-heatmap-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        default_color_range = [
            [255, 255, 178, 25],
            [254, 217, 118, 85],
            [254, 178, 76, 127],
            [253, 141, 60, 170],
            [240, 59, 32, 212],
            [189, 0, 38, 255],
        ]

        self.call_js_method(
            "addHeatmapLayer",
            id=layer_id,
            data=processed_data,
            getPosition=get_position,
            getWeight=get_weight,
            radiusPixels=radius_pixels,
            intensity=intensity,
            threshold=threshold,
            colorRange=color_range or default_color_range,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "deck-heatmap",
            },
        }
        self._add_to_layer_dict(layer_id, "Deck.gl")

    # -------------------------------------------------------------------------
    # Grid Layer (deck.gl)
    # -------------------------------------------------------------------------

    def add_grid_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_position: Union[str, Any] = "coordinates",
        cell_size: float = 200,
        elevation_scale: float = 4,
        extruded: bool = True,
        color_range: Optional[List[List[int]]] = None,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add a grid layer for square grid aggregation using deck.gl.

        Grid layers aggregate points into square grid cells and render them
        with height and color based on point density.

        Args:
            data: Array of data objects with position coordinates.
            name: Layer ID. If None, auto-generated.
            get_position: Accessor for point position [lng, lat].
            cell_size: Grid cell size in meters.
            elevation_scale: Elevation multiplier for 3D cells.
            extruded: Whether to render as 3D cells.
            color_range: Color gradient [[r, g, b], ...].
            pickable: Whether layer responds to hover/click events.
            opacity: Layer opacity (0-1).
            **kwargs: Additional GridLayer props.

        Example:
            >>> from anymap_ts import MapLibreMap
            >>> m = MapLibreMap(pitch=45)
            >>> points = [
            ...     {"coordinates": [-122.4, 37.8]},
            ...     {"coordinates": [-122.41, 37.81]},
            ... ]
            >>> m.add_grid_layer(points, cell_size=500)
        """
        layer_id = name or f"grid-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        default_color_range = [
            [1, 152, 189],
            [73, 227, 206],
            [216, 254, 181],
            [254, 237, 177],
            [254, 173, 84],
            [209, 55, 78],
        ]

        self.call_js_method(
            "addGridLayer",
            id=layer_id,
            data=processed_data,
            getPosition=get_position,
            cellSize=cell_size,
            elevationScale=elevation_scale,
            extruded=extruded,
            colorRange=color_range or default_color_range,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "grid",
            },
        }
        self._add_to_layer_dict(layer_id, "Deck.gl")

    # -------------------------------------------------------------------------
    # Icon Layer (deck.gl)
    # -------------------------------------------------------------------------

    def add_icon_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_position: Union[str, Any] = "coordinates",
        get_icon: Union[str, Any] = "icon",
        get_size: Union[float, str] = 20,
        get_color: Optional[Union[List[int], str]] = None,
        icon_atlas: Optional[str] = None,
        icon_mapping: Optional[Dict] = None,
        pickable: bool = True,
        opacity: float = 1,
        **kwargs,
    ) -> None:
        """Add an icon layer for custom icon markers at scale using deck.gl.

        Icon layers render icons/images at specified positions, ideal for
        rendering large numbers of custom markers efficiently.

        Args:
            data: Array of data objects with position coordinates.
            name: Layer ID. If None, auto-generated.
            get_position: Accessor for icon position [lng, lat].
            get_icon: Accessor for icon name in icon_mapping.
            get_size: Accessor for icon size in pixels.
            get_color: Accessor for icon tint color [r, g, b, a].
                Default: [255, 255, 255, 255] (white, no tint).
            icon_atlas: URL to icon atlas image.
            icon_mapping: Dict mapping icon names to atlas coordinates.
            pickable: Whether layer responds to hover/click events.
            opacity: Layer opacity (0-1).
            **kwargs: Additional IconLayer props.

        Example:
            >>> from anymap_ts import MapLibreMap
            >>> m = MapLibreMap()
            >>> markers = [
            ...     {"coordinates": [-122.4, 37.8], "icon": "marker", "size": 30},
            ... ]
            >>> m.add_icon_layer(markers, get_size="size")
        """
        layer_id = name or f"icon-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addIconLayer",
            id=layer_id,
            data=processed_data,
            getPosition=get_position,
            getIcon=get_icon,
            getSize=get_size,
            getColor=get_color or [255, 255, 255, 255],
            iconAtlas=icon_atlas,
            iconMapping=icon_mapping,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "icon",
            },
        }
        self._add_to_layer_dict(layer_id, "Deck.gl")

    # -------------------------------------------------------------------------
    # Text Layer (deck.gl)
    # -------------------------------------------------------------------------

    def add_text_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_position: Union[str, Any] = "coordinates",
        get_text: Union[str, Any] = "text",
        get_size: Union[float, str] = 12,
        get_color: Optional[Union[List[int], str]] = None,
        get_angle: Union[float, str] = 0,
        text_anchor: str = "middle",
        alignment_baseline: str = "center",
        pickable: bool = True,
        opacity: float = 1,
        **kwargs,
    ) -> None:
        """Add a text layer for label placement using deck.gl.

        Text layers render text labels at specified positions, ideal for
        annotating map features or creating label layers.

        Args:
            data: Array of data objects with position and text.
            name: Layer ID. If None, auto-generated.
            get_position: Accessor for text position [lng, lat].
            get_text: Accessor for text content string.
            get_size: Accessor for text size in pixels.
            get_color: Accessor for text color [r, g, b, a].
                Default: [0, 0, 0, 255] (black).
            get_angle: Accessor for text rotation in degrees.
            text_anchor: Horizontal alignment ('start', 'middle', 'end').
            alignment_baseline: Vertical alignment ('top', 'center', 'bottom').
            pickable: Whether layer responds to hover/click events.
            opacity: Layer opacity (0-1).
            **kwargs: Additional TextLayer props.

        Example:
            >>> from anymap_ts import MapLibreMap
            >>> m = MapLibreMap()
            >>> labels = [
            ...     {"coordinates": [-122.4, 37.8], "text": "San Francisco"},
            ...     {"coordinates": [-118.2, 34.1], "text": "Los Angeles"},
            ... ]
            >>> m.add_text_layer(labels, get_size=16)
        """
        layer_id = name or f"text-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addTextLayer",
            id=layer_id,
            data=processed_data,
            getPosition=get_position,
            getText=get_text,
            getSize=get_size,
            getColor=get_color or [0, 0, 0, 255],
            getAngle=get_angle,
            getTextAnchor=text_anchor,
            getAlignmentBaseline=alignment_baseline,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "text",
            },
        }
        self._add_to_layer_dict(layer_id, "Deck.gl")

    # -------------------------------------------------------------------------
    # GeoJSON Layer (deck.gl)
    # -------------------------------------------------------------------------

    def add_geojson_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_fill_color: Optional[Union[List[int], str]] = None,
        get_line_color: Optional[Union[List[int], str]] = None,
        get_line_width: Union[float, str] = 1,
        get_point_radius: Union[float, str] = 5,
        get_elevation: Union[float, str] = 0,
        extruded: bool = False,
        wireframe: bool = False,
        filled: bool = True,
        stroked: bool = True,
        line_width_min_pixels: float = 1,
        point_radius_min_pixels: float = 2,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add a GeoJSON layer with auto-styling using deck.gl.

        GeoJSON layers render GeoJSON features with automatic geometry type
        detection and styling, supporting points, lines, and polygons.

        Args:
            data: GeoJSON object, URL, or file path.
            name: Layer ID. If None, auto-generated.
            get_fill_color: Accessor for fill color [r, g, b, a].
                Default: [51, 136, 255, 128].
            get_line_color: Accessor for stroke color [r, g, b, a].
                Default: [0, 0, 0, 255].
            get_line_width: Accessor for stroke width.
            get_point_radius: Accessor for point radius.
            get_elevation: Accessor for 3D extrusion height.
            extruded: Whether to render as 3D features.
            wireframe: Whether to render wireframe (extruded only).
            filled: Whether to fill features.
            stroked: Whether to draw stroke.
            line_width_min_pixels: Minimum stroke width in pixels.
            point_radius_min_pixels: Minimum point radius in pixels.
            pickable: Whether layer responds to hover/click events.
            opacity: Layer opacity (0-1).
            **kwargs: Additional GeoJsonLayer props.

        Example:
            >>> from anymap_ts import MapLibreMap
            >>> m = MapLibreMap()
            >>> m.add_geojson_layer(
            ...     "https://example.com/data.geojson",
            ...     get_fill_color=[255, 0, 0, 128],
            ... )
        """
        layer_id = name or f"geojson-deck-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addGeoJsonLayer",
            id=layer_id,
            data=processed_data,
            getFillColor=get_fill_color or [51, 136, 255, 128],
            getLineColor=get_line_color or [0, 0, 0, 255],
            getLineWidth=get_line_width,
            getPointRadius=get_point_radius,
            getElevation=get_elevation,
            extruded=extruded,
            wireframe=wireframe,
            filled=filled,
            stroked=stroked,
            lineWidthMinPixels=line_width_min_pixels,
            pointRadiusMinPixels=point_radius_min_pixels,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "geojson-deck",
            },
        }
        self._add_to_layer_dict(layer_id, "Deck.gl")

    # -------------------------------------------------------------------------
    # Contour Layer (deck.gl)
    # -------------------------------------------------------------------------

    def add_contour_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_position: Union[str, Any] = "coordinates",
        get_weight: Union[float, str] = 1,
        cell_size: float = 200,
        contours: Optional[List[Dict]] = None,
        pickable: bool = True,
        opacity: float = 1,
        **kwargs,
    ) -> None:
        """Add a contour layer for isoline/isoband generation using deck.gl.

        Contour layers aggregate point data and generate isolines or isobands,
        ideal for density visualization and topographic-style maps.

        Args:
            data: Array of data objects with position coordinates.
            name: Layer ID. If None, auto-generated.
            get_position: Accessor for point position [lng, lat].
            get_weight: Accessor for point weight value.
            cell_size: Grid cell size for aggregation in meters.
            contours: Contour definitions [{threshold, color, strokeWidth}, ...].
            pickable: Whether layer responds to hover/click events.
            opacity: Layer opacity (0-1).
            **kwargs: Additional ContourLayer props.

        Example:
            >>> from anymap_ts import MapLibreMap
            >>> m = MapLibreMap()
            >>> points = [
            ...     {"coordinates": [-122.4, 37.8], "weight": 5},
            ...     {"coordinates": [-122.41, 37.81], "weight": 10},
            ... ]
            >>> m.add_contour_layer(points, contours=[
            ...     {"threshold": 1, "color": [255, 255, 178], "strokeWidth": 1},
            ...     {"threshold": 5, "color": [253, 141, 60], "strokeWidth": 2},
            ... ])
        """
        layer_id = name or f"contour-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        default_contours = [
            {"threshold": 1, "color": [255, 255, 255], "strokeWidth": 1},
            {"threshold": 5, "color": [51, 136, 255], "strokeWidth": 2},
            {"threshold": 10, "color": [0, 0, 255], "strokeWidth": 3},
        ]

        self.call_js_method(
            "addContourLayer",
            id=layer_id,
            data=processed_data,
            getPosition=get_position,
            getWeight=get_weight,
            cellSize=cell_size,
            contours=contours or default_contours,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "contour",
            },
        }
        self._add_to_layer_dict(layer_id, "Deck.gl")

    # -------------------------------------------------------------------------
    # Screen Grid Layer (deck.gl)
    # -------------------------------------------------------------------------

    def add_screen_grid_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_position: Union[str, Any] = "coordinates",
        get_weight: Union[float, str] = 1,
        cell_size_pixels: float = 50,
        color_range: Optional[List[List[int]]] = None,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add a screen grid layer for screen-space grid aggregation using deck.gl.

        Screen grid layers aggregate points into a grid in screen space,
        providing a fast overview of point density that updates on zoom/pan.

        Args:
            data: Array of data objects with position coordinates.
            name: Layer ID. If None, auto-generated.
            get_position: Accessor for point position [lng, lat].
            get_weight: Accessor for point weight value.
            cell_size_pixels: Grid cell size in screen pixels.
            color_range: Color gradient [[r, g, b, a], ...].
            pickable: Whether layer responds to hover/click events.
            opacity: Layer opacity (0-1).
            **kwargs: Additional ScreenGridLayer props.

        Example:
            >>> from anymap_ts import MapLibreMap
            >>> m = MapLibreMap()
            >>> points = [
            ...     {"coordinates": [-122.4, 37.8]},
            ...     {"coordinates": [-122.41, 37.81]},
            ... ]
            >>> m.add_screen_grid_layer(points, cell_size_pixels=30)
        """
        layer_id = name or f"screengrid-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        default_color_range = [
            [255, 255, 178, 25],
            [254, 217, 118, 85],
            [254, 178, 76, 127],
            [253, 141, 60, 170],
            [240, 59, 32, 212],
            [189, 0, 38, 255],
        ]

        self.call_js_method(
            "addScreenGridLayer",
            id=layer_id,
            data=processed_data,
            getPosition=get_position,
            getWeight=get_weight,
            cellSizePixels=cell_size_pixels,
            colorRange=color_range or default_color_range,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "screengrid",
            },
        }
        self._add_to_layer_dict(layer_id, "Deck.gl")

    # -------------------------------------------------------------------------
    # Trips Layer (deck.gl)
    # -------------------------------------------------------------------------

    def add_trips_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_path: Union[str, Any] = "waypoints",
        get_timestamps: Union[str, Any] = "timestamps",
        get_color: Optional[Union[List[int], str]] = None,
        width_min_pixels: float = 2,
        trail_length: float = 180,
        current_time: float = 0,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add a trips layer for animated trip/trajectory playback using deck.gl.

        Trips layers render animated paths showing movement over time, ideal
        for visualizing vehicle routes, migration patterns, or time-based data.

        Args:
            data: Array of trip objects with waypoints and timestamps.
            name: Layer ID. If None, auto-generated.
            get_path: Accessor for waypoint coordinates [[lng, lat], ...].
            get_timestamps: Accessor for timestamps at each waypoint.
            get_color: Accessor for trip color [r, g, b] or [r, g, b, a].
                Default: [253, 128, 93].
            width_min_pixels: Minimum trail width in pixels.
            trail_length: Trail length in timestamp units.
            current_time: Current animation time.
            pickable: Whether layer responds to hover/click events.
            opacity: Layer opacity (0-1).
            **kwargs: Additional TripsLayer props.

        Example:
            >>> from anymap_ts import MapLibreMap
            >>> m = MapLibreMap()
            >>> trips = [
            ...     {
            ...         "waypoints": [[-122.4, 37.8], [-122.5, 37.7]],
            ...         "timestamps": [0, 100]
            ...     }
            ... ]
            >>> m.add_trips_layer(trips, trail_length=200, current_time=50)
        """
        layer_id = name or f"trips-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addTripsLayer",
            id=layer_id,
            data=processed_data,
            getPath=get_path,
            getTimestamps=get_timestamps,
            getColor=get_color or [253, 128, 93],
            widthMinPixels=width_min_pixels,
            trailLength=trail_length,
            currentTime=current_time,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "trips",
            },
        }
        self._add_to_layer_dict(layer_id, "Deck.gl")

    # -------------------------------------------------------------------------
    # Line Layer (deck.gl)
    # -------------------------------------------------------------------------

    def add_line_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_source_position: Union[str, Any] = "sourcePosition",
        get_target_position: Union[str, Any] = "targetPosition",
        get_color: Optional[Union[List[int], str]] = None,
        get_width: Union[float, str] = 1,
        width_min_pixels: float = 1,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add a line layer for origin-destination line visualization using deck.gl.

        Line layers render straight line segments between source and target
        positions. Unlike arc layers, lines are drawn without curvature.

        Args:
            data: Array of line objects with source/target positions.
            name: Layer ID. If None, auto-generated.
            get_source_position: Accessor for source position [lng, lat].
            get_target_position: Accessor for target position [lng, lat].
            get_color: Accessor for line color [r, g, b] or [r, g, b, a].
                Default: [51, 136, 255, 200] (blue).
            get_width: Accessor for line width.
            width_min_pixels: Minimum line width in pixels.
            pickable: Whether layer responds to hover/click events.
            opacity: Layer opacity (0-1).
            **kwargs: Additional LineLayer props.

        Example:
            >>> from anymap_ts import MapLibreMap
            >>> m = MapLibreMap()
            >>> lines = [
            ...     {"sourcePosition": [-122.4, 37.8], "targetPosition": [-73.9, 40.7]},
            ... ]
            >>> m.add_line_layer(lines, get_color=[0, 128, 255], get_width=2)
        """
        layer_id = name or f"line-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addLineLayer",
            id=layer_id,
            data=processed_data,
            getSourcePosition=get_source_position,
            getTargetPosition=get_target_position,
            getColor=get_color or [51, 136, 255, 200],
            getWidth=get_width,
            widthMinPixels=width_min_pixels,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "line",
            },
        }
        self._add_to_layer_dict(layer_id, "Deck.gl")

    # -------------------------------------------------------------------------
    # Generic Deck.gl Layer
    # -------------------------------------------------------------------------

    def add_deckgl_layer(
        self,
        layer_type: str,
        data: Any,
        name: Optional[str] = None,
        **kwargs,
    ) -> None:
        """Add a generic deck.gl layer to the map.

        This method provides a flexible way to add any supported deck.gl layer
        type using a single interface. For commonly used layers, prefer the
        specific methods (e.g., add_scatterplot_layer) for better IDE support.

        Args:
            layer_type: The deck.gl layer type (e.g., 'ScatterplotLayer',
                'ArcLayer', 'HexagonLayer').
            data: Array of data objects or GeoJSON.
            name: Layer ID. If None, auto-generated from layer_type.
            **kwargs: Layer-specific properties passed directly to deck.gl.

        Example:
            >>> from anymap_ts import MapLibreMap
            >>> m = MapLibreMap()
            >>> m.add_deckgl_layer(
            ...     "TripsLayer",
            ...     data=trips_data,
            ...     getPath="waypoints",
            ...     getTimestamps="timestamps",
            ...     trailLength=180,
            ... )
        """
        layer_type_clean = layer_type.replace("Layer", "")
        prefix = layer_type_clean.lower()
        layer_id = name or f"{prefix}-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addDeckGLLayer",
            layerType=layer_type,
            id=layer_id,
            data=processed_data,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": layer_type,
            },
        }
        self._add_to_layer_dict(layer_id, "Deck.gl")

    def remove_deck_layer(self, layer_id: str) -> None:
        """Remove a deck.gl layer from the map.

        Args:
            layer_id: Layer identifier to remove.
        """
        self._remove_layer_internal(layer_id, "removeDeckLayer")

    # -------------------------------------------------------------------------
    # Column Layer (deck.gl)
    # -------------------------------------------------------------------------

    def add_column_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_position: Union[str, Any] = "coordinates",
        get_fill_color: Optional[Union[List[int], str]] = None,
        get_line_color: Optional[Union[List[int], str]] = None,
        get_elevation: Union[float, str] = 1000,
        radius: float = 1000,
        disk_resolution: int = 20,
        elevation_scale: float = 1,
        coverage: float = 1,
        extruded: bool = True,
        filled: bool = True,
        stroked: bool = False,
        wireframe: bool = False,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add a column layer for 3D bar chart visualization using deck.gl.

        Column layers render cylindrical columns at specified positions,
        ideal for 3D bar charts on a map.

        Args:
            data: Array of data objects with position coordinates.
            name: Layer ID. If None, auto-generated.
            get_position: Accessor for column position [lng, lat].
            get_fill_color: Accessor for fill color [r, g, b, a].
            get_line_color: Accessor for stroke color [r, g, b, a].
            get_elevation: Accessor for column height.
            radius: Column radius in meters.
            disk_resolution: Number of sides for column polygon.
            elevation_scale: Elevation multiplier.
            coverage: Column coverage (0-1).
            extruded: Whether to extrude columns.
            filled: Whether to fill columns.
            stroked: Whether to stroke columns.
            wireframe: Whether to render as wireframe.
            pickable: Whether layer responds to hover/click events.
            opacity: Layer opacity (0-1).
            **kwargs: Additional ColumnLayer props.

        Example:
            >>> from anymap_ts import MapLibreMap
            >>> m = MapLibreMap(pitch=45)
            >>> data = [
            ...     {"coordinates": [-122.4, 37.8], "value": 500},
            ...     {"coordinates": [-122.5, 37.7], "value": 1000},
            ... ]
            >>> m.add_column_layer(data, get_elevation="value", radius=500)
        """
        layer_id = name or f"column-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addColumnLayer",
            id=layer_id,
            data=processed_data,
            getPosition=get_position,
            getFillColor=get_fill_color or [255, 140, 0, 200],
            getLineColor=get_line_color or [0, 0, 0, 255],
            getElevation=get_elevation,
            radius=radius,
            diskResolution=disk_resolution,
            elevationScale=elevation_scale,
            coverage=coverage,
            extruded=extruded,
            filled=filled,
            stroked=stroked,
            wireframe=wireframe,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {"id": layer_id, "type": "column"},
        }
        self._add_to_layer_dict(layer_id, "Deck.gl")

    # -------------------------------------------------------------------------
    # Bitmap Layer (deck.gl)
    # -------------------------------------------------------------------------

    def add_bitmap_layer(
        self,
        image: str,
        bounds: List[float],
        name: Optional[str] = None,
        opacity: float = 1.0,
        visible: bool = True,
        pickable: bool = False,
        desaturate: float = 0,
        transparent_color: Optional[List[int]] = None,
        tint_color: Optional[List[int]] = None,
        **kwargs,
    ) -> None:
        """Add a bitmap layer for image overlay with GPU rendering using deck.gl.

        Args:
            image: URL or data URI of the image.
            bounds: Bounding box [west, south, east, north].
            name: Layer ID. If None, auto-generated.
            opacity: Layer opacity (0-1).
            visible: Whether layer is visible.
            pickable: Whether layer responds to hover/click events.
            desaturate: Desaturation amount (0-1).
            transparent_color: Color to make transparent [r, g, b, a].
            tint_color: Color to tint the image [r, g, b].
            **kwargs: Additional BitmapLayer props.

        Example:
            >>> from anymap_ts import MapLibreMap
            >>> m = MapLibreMap()
            >>> m.add_bitmap_layer(
            ...     "https://example.com/overlay.png",
            ...     bounds=[-122.5, 37.7, -122.3, 37.9],
            ... )
        """
        layer_id = name or f"bitmap-{len(self._layers)}"

        self.call_js_method(
            "addBitmapLayer",
            id=layer_id,
            image=image,
            bounds=bounds,
            opacity=opacity,
            visible=visible,
            pickable=pickable,
            desaturate=desaturate,
            transparentColor=transparent_color or [0, 0, 0, 0],
            tintColor=tint_color or [255, 255, 255],
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {"id": layer_id, "type": "bitmap"},
        }
        self._add_to_layer_dict(layer_id, "Deck.gl")

    # -------------------------------------------------------------------------
    # Solid Polygon Layer (deck.gl)
    # -------------------------------------------------------------------------

    def add_solid_polygon_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_polygon: Union[str, Any] = "polygon",
        get_fill_color: Optional[Union[List[int], str]] = None,
        get_line_color: Optional[Union[List[int], str]] = None,
        get_elevation: Union[float, str] = 0,
        filled: bool = True,
        extruded: bool = False,
        wireframe: bool = False,
        elevation_scale: float = 1,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add a solid polygon layer for extruded 3D polygon visualization using deck.gl.

        Args:
            data: Array of data objects with polygon coordinates.
            name: Layer ID. If None, auto-generated.
            get_polygon: Accessor for polygon coordinates.
            get_fill_color: Accessor for fill color [r, g, b, a].
            get_line_color: Accessor for stroke color [r, g, b, a].
            get_elevation: Accessor for 3D extrusion height.
            filled: Whether to fill polygons.
            extruded: Whether to render as 3D polygons.
            wireframe: Whether to render wireframe.
            elevation_scale: Elevation multiplier.
            pickable: Whether layer responds to hover/click events.
            opacity: Layer opacity (0-1).
            **kwargs: Additional SolidPolygonLayer props.

        Example:
            >>> from anymap_ts import MapLibreMap
            >>> m = MapLibreMap(pitch=45)
            >>> data = [
            ...     {"polygon": [[-122.4, 37.8], [-122.5, 37.7], [-122.3, 37.7]], "height": 500},
            ... ]
            >>> m.add_solid_polygon_layer(data, extruded=True, get_elevation="height")
        """
        layer_id = name or f"solidpolygon-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addSolidPolygonLayer",
            id=layer_id,
            data=processed_data,
            getPolygon=get_polygon,
            getFillColor=get_fill_color or [51, 136, 255, 128],
            getLineColor=get_line_color or [0, 0, 0, 255],
            getElevation=get_elevation,
            filled=filled,
            extruded=extruded,
            wireframe=wireframe,
            elevationScale=elevation_scale,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {"id": layer_id, "type": "solidpolygon"},
        }
        self._add_to_layer_dict(layer_id, "Deck.gl")

    # -------------------------------------------------------------------------
    # Grid Cell Layer (deck.gl)
    # -------------------------------------------------------------------------

    def add_grid_cell_layer(
        self,
        data: Any,
        name: Optional[str] = None,
        get_position: Union[str, Any] = "coordinates",
        get_color: Optional[Union[List[int], str]] = None,
        get_elevation: Union[float, str] = 1000,
        cell_size: float = 200,
        coverage: float = 1,
        elevation_scale: float = 1,
        extruded: bool = True,
        pickable: bool = True,
        opacity: float = 0.8,
        **kwargs,
    ) -> None:
        """Add a grid cell layer for pre-aggregated grid visualization using deck.gl.

        Args:
            data: Array of data objects with position coordinates.
            name: Layer ID. If None, auto-generated.
            get_position: Accessor for cell position [lng, lat].
            get_color: Accessor for cell color [r, g, b, a].
            get_elevation: Accessor for cell height.
            cell_size: Cell size in meters.
            coverage: Cell coverage (0-1).
            elevation_scale: Elevation multiplier.
            extruded: Whether to extrude cells.
            pickable: Whether layer responds to hover/click events.
            opacity: Layer opacity (0-1).
            **kwargs: Additional GridCellLayer props.

        Example:
            >>> from anymap_ts import MapLibreMap
            >>> m = MapLibreMap(pitch=45)
            >>> data = [
            ...     {"coordinates": [-122.4, 37.8], "value": 500},
            ... ]
            >>> m.add_grid_cell_layer(data, get_elevation="value")
        """
        layer_id = name or f"gridcell-{len(self._layers)}"
        processed_data = self._process_deck_data(data)

        self.call_js_method(
            "addGridCellLayer",
            id=layer_id,
            data=processed_data,
            getPosition=get_position,
            getColor=get_color or [255, 140, 0, 200],
            getElevation=get_elevation,
            cellSize=cell_size,
            coverage=coverage,
            elevationScale=elevation_scale,
            extruded=extruded,
            pickable=pickable,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {"id": layer_id, "type": "gridcell"},
        }
        self._add_to_layer_dict(layer_id, "Deck.gl")

    # -------------------------------------------------------------------------
    # LiDAR Layers (maplibre-gl-lidar)
    # -------------------------------------------------------------------------

    def add_lidar_control(
        self,
        position: str = "top-right",
        collapsed: bool = True,
        title: str = "LiDAR Viewer",
        point_size: float = 2,
        opacity: float = 1.0,
        color_scheme: str = "elevation",
        use_percentile: bool = True,
        point_budget: int = 1000000,
        pickable: bool = False,
        auto_zoom: bool = True,
        copc_loading_mode: Optional[str] = None,
        streaming_point_budget: int = 5000000,
        panel_max_height: int = 600,
        **kwargs,
    ) -> None:
        """Add an interactive LiDAR control panel.

        The LiDAR control provides a UI panel for loading, visualizing, and
        styling LiDAR point cloud files (LAS, LAZ, COPC formats).

        Args:
            position: Control position ('top-left', 'top-right', 'bottom-left', 'bottom-right').
            collapsed: Whether the panel starts collapsed.
            title: Title displayed on the panel.
            point_size: Point size in pixels.
            opacity: Layer opacity (0-1).
            color_scheme: Color scheme ('elevation', 'intensity', 'classification', 'rgb').
            use_percentile: Use 2-98% percentile for color scaling.
            point_budget: Maximum number of points to display.
            pickable: Enable hover/click interactions.
            auto_zoom: Auto-zoom to point cloud after loading.
            copc_loading_mode: COPC loading mode ('full' or 'dynamic').
            streaming_point_budget: Point budget for streaming mode.
            panel_max_height: Maximum height of the panel in pixels.
            **kwargs: Additional control options.

        Example:
            >>> from anymap_ts import MapLibreMap
            >>> m = MapLibreMap(pitch=60)
            >>> m.add_lidar_control(color_scheme="classification", pickable=True)
        """
        self.call_js_method(
            "addLidarControl",
            position=position,
            collapsed=collapsed,
            title=title,
            pointSize=point_size,
            opacity=opacity,
            colorScheme=color_scheme,
            usePercentile=use_percentile,
            pointBudget=point_budget,
            pickable=pickable,
            autoZoom=auto_zoom,
            copcLoadingMode=copc_loading_mode,
            streamingPointBudget=streaming_point_budget,
            panelMaxHeight=panel_max_height,
            **kwargs,
        )
        self._controls = {
            **self._controls,
            "lidar-control": {"position": position, "collapsed": collapsed},
        }

    def add_lidar_layer(
        self,
        source: Union[str, Path],
        name: Optional[str] = None,
        color_scheme: str = "elevation",
        point_size: float = 2,
        opacity: float = 1.0,
        pickable: bool = True,
        auto_zoom: bool = True,
        streaming_mode: bool = True,
        point_budget: int = 1000000,
        **kwargs,
    ) -> None:
        """Load and display a LiDAR file from URL or local path.

        Supports LAS, LAZ, and COPC (Cloud-Optimized Point Cloud) formats.
        For local files, the file is read and sent as base64 to JavaScript.
        For URLs, the data is loaded directly via streaming when possible.

        Args:
            source: URL or local file path to the LiDAR file.
            name: Layer identifier. If None, auto-generated.
            color_scheme: Color scheme ('elevation', 'intensity', 'classification', 'rgb').
            point_size: Point size in pixels.
            opacity: Layer opacity (0-1).
            pickable: Enable hover/click interactions.
            auto_zoom: Auto-zoom to point cloud after loading.
            streaming_mode: Use streaming mode for large COPC files.
            point_budget: Maximum number of points to display.
            **kwargs: Additional layer options.

        Example:
            >>> from anymap_ts import MapLibreMap
            >>> m = MapLibreMap(center=[-123.07, 44.05], zoom=14, pitch=60)
            >>> m.add_lidar_layer(
            ...     source="https://s3.amazonaws.com/hobu-lidar/autzen-classified.copc.laz",
            ...     name="autzen",
            ...     color_scheme="classification",
            ... )
        """
        layer_id = name or f"lidar-{len(self._layers)}"

        # Check if source is a local file
        source_path = Path(source) if isinstance(source, (str, Path)) else None
        is_local = source_path is not None and source_path.exists()

        if is_local:
            # Read local file and encode as base64
            import base64

            with open(source_path, "rb") as f:
                file_data = f.read()
            source_b64 = base64.b64encode(file_data).decode("utf-8")

            self.call_js_method(
                "addLidarLayer",
                source=source_b64,
                name=layer_id,
                isBase64=True,
                filename=source_path.name,
                colorScheme=color_scheme,
                pointSize=point_size,
                opacity=opacity,
                pickable=pickable,
                autoZoom=auto_zoom,
                streamingMode=streaming_mode,
                pointBudget=point_budget,
                **kwargs,
            )
        else:
            # Load from URL
            self.call_js_method(
                "addLidarLayer",
                source=str(source),
                name=layer_id,
                isBase64=False,
                colorScheme=color_scheme,
                pointSize=point_size,
                opacity=opacity,
                pickable=pickable,
                autoZoom=auto_zoom,
                streamingMode=streaming_mode,
                pointBudget=point_budget,
                **kwargs,
            )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "lidar",
                "source": str(source),
            },
        }
        self._add_to_layer_dict(layer_id, "LiDAR")

    def remove_lidar_layer(self, layer_id: Optional[str] = None) -> None:
        """Remove a LiDAR layer.

        Args:
            layer_id: Layer identifier to remove. If None, removes all LiDAR layers.
        """
        if layer_id:
            if layer_id in self._layers:
                layers = dict(self._layers)
                del layers[layer_id]
                self._layers = layers
            self.call_js_method("removeLidarLayer", id=layer_id)
        else:
            # Remove all lidar layers
            layers = dict(self._layers)
            self._layers = {k: v for k, v in layers.items() if v.get("type") != "lidar"}
            self.call_js_method("removeLidarLayer")

    def set_lidar_color_scheme(self, color_scheme: str) -> None:
        """Set the LiDAR color scheme.

        Args:
            color_scheme: Color scheme ('elevation', 'intensity', 'classification', 'rgb').
        """
        self.call_js_method("setLidarColorScheme", colorScheme=color_scheme)

    def set_lidar_point_size(self, point_size: float) -> None:
        """Set the LiDAR point size.

        Args:
            point_size: Point size in pixels.
        """
        self.call_js_method("setLidarPointSize", pointSize=point_size)

    def set_lidar_opacity(self, opacity: float) -> None:
        """Set the LiDAR layer opacity.

        Args:
            opacity: Opacity value between 0 and 1.
        """
        self.call_js_method("setLidarOpacity", opacity=opacity)

    # -------------------------------------------------------------------------
    # maplibre-gl-components UI Controls
    # -------------------------------------------------------------------------

    def add_pmtiles_control(
        self,
        position: str = "top-right",
        collapsed: bool = True,
        default_url: Optional[str] = None,
        load_default_url: bool = False,
        default_opacity: float = 1.0,
        default_fill_color: str = "steelblue",
        default_line_color: str = "#333",
        default_pickable: bool = True,
        **kwargs,
    ) -> None:
        """Add a PMTiles layer control for loading PMTiles files via UI.

        This provides an interactive panel for users to enter PMTiles URLs
        and visualize vector or raster tile data.

        Args:
            position: Control position ('top-left', 'top-right', 'bottom-left', 'bottom-right').
            collapsed: Whether the panel starts collapsed.
            default_url: Default PMTiles URL to pre-fill.
            load_default_url: Whether to auto-load the default URL.
            default_opacity: Default layer opacity (0-1).
            default_fill_color: Default fill color for vector polygons.
            default_line_color: Default line color for vector lines.
            default_pickable: Whether features are clickable by default.
            **kwargs: Additional control options.

        Example:
            >>> from anymap_ts import MapLibreMap
            >>> m = MapLibreMap()
            >>> m.add_pmtiles_control(
            ...     default_url="https://pmtiles.io/protomaps(vector)ODbL_firenze.pmtiles",
            ...     load_default_url=True
            ... )
        """
        self.call_js_method(
            "addPMTilesControl",
            position=position,
            collapsed=collapsed,
            defaultUrl=default_url or "",
            loadDefaultUrl=load_default_url,
            defaultOpacity=default_opacity,
            defaultFillColor=default_fill_color,
            defaultLineColor=default_line_color,
            defaultPickable=default_pickable,
            **kwargs,
        )
        self._controls = {
            **self._controls,
            "pmtiles-control": {"position": position, "collapsed": collapsed},
        }

    def add_cog_control(
        self,
        position: str = "top-right",
        collapsed: bool = True,
        default_url: Optional[str] = None,
        load_default_url: bool = False,
        default_opacity: float = 1.0,
        default_colormap: str = "viridis",
        default_bands: str = "1",
        default_rescale_min: float = 0,
        default_rescale_max: float = 255,
        **kwargs,
    ) -> None:
        """Add a COG layer control for loading Cloud Optimized GeoTIFFs via UI.

        This provides an interactive panel for users to enter COG URLs
        and configure visualization parameters like colormap and rescaling.

        Args:
            position: Control position ('top-left', 'top-right', 'bottom-left', 'bottom-right').
            collapsed: Whether the panel starts collapsed.
            default_url: Default COG URL to pre-fill.
            load_default_url: Whether to auto-load the default URL.
            default_opacity: Default layer opacity (0-1).
            default_colormap: Default colormap name.
            default_bands: Default bands (e.g., '1' or '1,2,3').
            default_rescale_min: Default minimum value for rescaling.
            default_rescale_max: Default maximum value for rescaling.
            **kwargs: Additional control options.

        Example:
            >>> from anymap_ts import MapLibreMap
            >>> m = MapLibreMap()
            >>> m.add_cog_control(
            ...     default_url="https://example.com/cog.tif",
            ...     default_colormap="terrain"
            ... )
        """
        self.call_js_method(
            "addCogControl",
            position=position,
            collapsed=collapsed,
            defaultUrl=default_url or "",
            loadDefaultUrl=load_default_url,
            defaultOpacity=default_opacity,
            defaultColormap=default_colormap,
            defaultBands=default_bands,
            defaultRescaleMin=default_rescale_min,
            defaultRescaleMax=default_rescale_max,
            **kwargs,
        )
        self._controls = {
            **self._controls,
            "cog-control": {"position": position, "collapsed": collapsed},
        }

    def add_zarr_control(
        self,
        position: str = "top-right",
        collapsed: bool = True,
        default_url: Optional[str] = None,
        load_default_url: bool = False,
        default_opacity: float = 1.0,
        default_variable: str = "",
        default_clim: Optional[Tuple[float, float]] = None,
        **kwargs,
    ) -> None:
        """Add a Zarr layer control for loading Zarr datasets via UI.

        This provides an interactive panel for users to enter Zarr URLs
        and configure visualization parameters.

        Args:
            position: Control position ('top-left', 'top-right', 'bottom-left', 'bottom-right').
            collapsed: Whether the panel starts collapsed.
            default_url: Default Zarr URL to pre-fill.
            load_default_url: Whether to auto-load the default URL.
            default_opacity: Default layer opacity (0-1).
            default_variable: Default variable name.
            default_clim: Default color limits (min, max).
            **kwargs: Additional control options.

        Example:
            >>> from anymap_ts import MapLibreMap
            >>> m = MapLibreMap()
            >>> m.add_zarr_control(
            ...     default_url="https://example.com/data.zarr",
            ...     default_variable="temperature"
            ... )
        """
        self.call_js_method(
            "addZarrControl",
            position=position,
            collapsed=collapsed,
            defaultUrl=default_url or "",
            loadDefaultUrl=load_default_url,
            defaultOpacity=default_opacity,
            defaultVariable=default_variable,
            defaultClim=list(default_clim) if default_clim else [0, 1],
            **kwargs,
        )
        self._controls = {
            **self._controls,
            "zarr-control": {"position": position, "collapsed": collapsed},
        }

    def add_vector_control(
        self,
        position: str = "top-right",
        collapsed: bool = True,
        default_url: Optional[str] = None,
        load_default_url: bool = False,
        default_opacity: float = 1.0,
        default_fill_color: str = "#3388ff",
        default_stroke_color: str = "#3388ff",
        fit_bounds: bool = True,
        **kwargs,
    ) -> None:
        """Add a vector layer control for loading vector datasets from URLs.

        This provides an interactive panel for users to enter URLs to
        GeoJSON, GeoParquet, or FlatGeobuf datasets.

        Args:
            position: Control position ('top-left', 'top-right', 'bottom-left', 'bottom-right').
            collapsed: Whether the panel starts collapsed.
            default_url: Default vector URL to pre-fill.
            load_default_url: Whether to auto-load the default URL.
            default_opacity: Default layer opacity (0-1).
            default_fill_color: Default fill color for polygons.
            default_stroke_color: Default stroke color for lines/outlines.
            fit_bounds: Whether to fit map to loaded data bounds.
            **kwargs: Additional control options.

        Example:
            >>> from anymap_ts import MapLibreMap
            >>> m = MapLibreMap()
            >>> m.add_vector_control(
            ...     default_url="https://example.com/data.geojson",
            ...     default_fill_color="#ff0000"
            ... )
        """
        self.call_js_method(
            "addVectorControl",
            position=position,
            collapsed=collapsed,
            defaultUrl=default_url or "",
            loadDefaultUrl=load_default_url,
            defaultOpacity=default_opacity,
            defaultFillColor=default_fill_color,
            defaultStrokeColor=default_stroke_color,
            fitBounds=fit_bounds,
            **kwargs,
        )
        self._controls = {
            **self._controls,
            "vector-control": {"position": position, "collapsed": collapsed},
        }

    def add_control_grid(
        self,
        position: str = "top-right",
        default_controls: Optional[List[str]] = None,
        exclude: Optional[List[str]] = None,
        rows: Optional[int] = None,
        columns: Optional[int] = None,
        collapsed: bool = True,
        collapsible: bool = True,
        title: str = "",
        show_row_column_controls: bool = True,
        gap: int = 2,
        basemap_style_url: Optional[str] = None,
        exclude_layers: Optional[List[str]] = None,
        **kwargs,
    ) -> None:
        """Add a ControlGrid with all default tools or a custom subset.

        The ControlGrid provides a collapsible toolbar with up to 26 built-in
        controls (search, basemap, terrain, measure, draw, etc.) in a
        configurable grid layout.

        Args:
            position: Control position ('top-left', 'top-right', 'bottom-left',
                'bottom-right').
            default_controls: Explicit list of control names to include. If None,
                all 26 default controls are used (minus any in ``exclude``).
                Valid names: 'globe', 'fullscreen', 'north', 'terrain', 'search',
                'viewState', 'inspect', 'vectorDataset', 'basemap', 'measure',
                'geoEditor', 'bookmark', 'print', 'minimap', 'swipe',
                'streetView', 'addVector', 'cogLayer', 'zarrLayer',
                'pmtilesLayer', 'stacLayer', 'stacSearch', 'planetaryComputer',
                'gaussianSplat', 'lidar', 'usgsLidar'.
            exclude: Controls to remove from the default set. Ignored when
                ``default_controls`` is provided.
            rows: Number of grid rows (auto-calculated if None).
            columns: Number of grid columns (auto-calculated if None).
            collapsed: Whether the grid starts collapsed. Default True.
            collapsible: Whether the grid can be collapsed. Default True.
            title: Optional header title for the grid.
            show_row_column_controls: Show row/column input fields. Default True.
            gap: Gap between grid cells in pixels. Default 2.
            basemap_style_url: Basemap style URL for SwipeControl layer grouping.
                If None, the current map style is used automatically.
            exclude_layers: Layer ID patterns to exclude from SwipeControl
                (e.g., 'measure-*', 'gl-draw-*'). If None, sensible defaults
                are applied.
            **kwargs: Additional ControlGrid options.

        Example:
            >>> from anymap_ts import MapLibreMap
            >>> m = MapLibreMap()
            >>> m.add_control_grid()  # All 26 controls
            >>> # Or with customization:
            >>> m.add_control_grid(
            ...     exclude=["minimap", "streetView"],
            ...     collapsed=True,
            ... )
        """
        js_kwargs: Dict[str, Any] = {
            "position": position,
            "collapsed": collapsed,
            "collapsible": collapsible,
            "showRowColumnControls": show_row_column_controls,
            "gap": gap,
            **kwargs,
        }
        if default_controls is not None:
            js_kwargs["defaultControls"] = default_controls
        if exclude is not None:
            js_kwargs["exclude"] = exclude
        if rows is not None:
            js_kwargs["rows"] = rows
        if columns is not None:
            js_kwargs["columns"] = columns
        if title:
            js_kwargs["title"] = title
        if basemap_style_url is not None:
            js_kwargs["basemapStyleUrl"] = basemap_style_url
        if exclude_layers is not None:
            js_kwargs["excludeLayers"] = exclude_layers

        self.call_js_method("addControlGrid", **js_kwargs)
        # Save full config for HTML export
        control_config = {
            "position": position,
            "collapsed": collapsed,
            "collapsible": collapsible,
        }
        if default_controls is not None:
            control_config["defaultControls"] = default_controls
        if exclude is not None:
            control_config["exclude"] = exclude
        if rows is not None:
            control_config["rows"] = rows
        if columns is not None:
            control_config["columns"] = columns
        self._controls = {
            **self._controls,
            "control-grid": control_config,
        }

    # -------------------------------------------------------------------------
    # Colorbar
    # -------------------------------------------------------------------------

    def add_colorbar(
        self,
        colormap: str = "viridis",
        vmin: float = 0,
        vmax: float = 1,
        label: str = "",
        units: str = "",
        orientation: str = "horizontal",
        position: str = "bottom-right",
        bar_thickness: Optional[int] = None,
        bar_length: Optional[int] = None,
        ticks: Optional[Dict] = None,
        opacity: Optional[float] = None,
        colorbar_id: Optional[str] = None,
        **kwargs,
    ) -> None:
        """Add a continuous gradient colorbar to the map.

        Displays a color gradient legend with customizable colormaps,
        tick marks, labels, and positioning using maplibre-gl-components.

        Args:
            colormap: Colormap name (e.g., 'viridis', 'plasma', 'inferno',
                'magma', 'cividis', 'coolwarm', 'jet', 'terrain', etc.).
            vmin: Minimum value for the colorbar scale.
            vmax: Maximum value for the colorbar scale.
            label: Title/label displayed above or beside the colorbar.
            units: Unit string displayed after values (e.g., '°C', 'm').
            orientation: Orientation of the colorbar ('horizontal' or 'vertical').
            position: Control position ('top-left', 'top-right',
                'bottom-left', 'bottom-right').
            bar_thickness: Width/height of the gradient bar in pixels.
            bar_length: Length of the colorbar in pixels.
            ticks: Tick configuration dict (e.g., {'count': 5, 'precision': 2}).
            opacity: Opacity of the colorbar container (0-1).
            colorbar_id: Unique identifier. If None, auto-generated.
            **kwargs: Additional Colorbar options.

        Example:
            >>> m = Map()
            >>> m.add_cog_layer("https://example.com/dem.tif")
            >>> m.add_colorbar(
            ...     colormap="terrain",
            ...     vmin=0,
            ...     vmax=4000,
            ...     label="Elevation",
            ...     units="m",
            ... )
        """
        self._validate_position(position)

        cbar_id = (
            colorbar_id
            or f"colorbar-{len([k for k in self._controls.keys() if k.startswith('colorbar')])}"
        )

        js_kwargs: Dict[str, Any] = {
            "colormap": colormap,
            "vmin": vmin,
            "vmax": vmax,
            "label": label,
            "units": units,
            "orientation": orientation,
            "position": position,
            "colorbarId": cbar_id,
            **kwargs,
        }
        if bar_thickness is not None:
            js_kwargs["barThickness"] = bar_thickness
        if bar_length is not None:
            js_kwargs["barLength"] = bar_length
        if ticks is not None:
            js_kwargs["ticks"] = ticks
        if opacity is not None:
            js_kwargs["opacity"] = opacity

        self.call_js_method("addColorbar", **js_kwargs)

        self._controls = {
            **self._controls,
            cbar_id: {
                "type": "colorbar",
                "colormap": colormap,
                "vmin": vmin,
                "vmax": vmax,
                "label": label,
                "units": units,
                "orientation": orientation,
                "position": position,
            },
        }

    def remove_colorbar(self, colorbar_id: Optional[str] = None) -> None:
        """Remove a colorbar from the map.

        Args:
            colorbar_id: Colorbar identifier to remove. If None, removes
                all colorbars.
        """
        if colorbar_id is None:
            cbar_keys = [k for k in self._controls.keys() if k.startswith("colorbar")]
            for key in cbar_keys:
                self.call_js_method("removeColorbar", colorbarId=key)
            self._controls = {
                k: v for k, v in self._controls.items() if not k.startswith("colorbar")
            }
        else:
            self.call_js_method("removeColorbar", colorbarId=colorbar_id)
            if colorbar_id in self._controls:
                controls = dict(self._controls)
                del controls[colorbar_id]
                self._controls = controls

    def update_colorbar(self, colorbar_id: Optional[str] = None, **kwargs) -> None:
        """Update an existing colorbar's properties.

        Args:
            colorbar_id: Colorbar identifier to update. If None, updates
                the first colorbar found.
            **kwargs: Properties to update (colormap, vmin, vmax, label,
                units, orientation, bar_thickness, bar_length, ticks, opacity).
        """
        if colorbar_id is None:
            cbar_keys = [k for k in self._controls.keys() if k.startswith("colorbar")]
            if not cbar_keys:
                raise ValueError("No colorbar found to update")
            colorbar_id = cbar_keys[0]

        if colorbar_id not in self._controls:
            raise ValueError(f"Colorbar '{colorbar_id}' not found")

        js_kwargs: Dict[str, Any] = {"colorbarId": colorbar_id}
        key_map = {
            "bar_thickness": "barThickness",
            "bar_length": "barLength",
        }
        for key, value in kwargs.items():
            js_key = key_map.get(key, key)
            js_kwargs[js_key] = value

        self.call_js_method("updateColorbar", **js_kwargs)

        for key, value in kwargs.items():
            if key in self._controls.get(colorbar_id, {}):
                self._controls[colorbar_id][key] = value

    # -------------------------------------------------------------------------
    # Search / Geocoder Control
    # -------------------------------------------------------------------------

    def add_search_control(
        self,
        position: str = "top-left",
        placeholder: str = "Search places...",
        collapsed: bool = True,
        fly_to_zoom: int = 14,
        show_marker: bool = True,
        marker_color: str = "#4264fb",
        **kwargs,
    ) -> None:
        """Add a search/geocoder control using Nominatim.

        Provides place search functionality with autocomplete results.
        Results are geocoded via OpenStreetMap Nominatim service.

        Args:
            position: Control position ('top-left', 'top-right',
                'bottom-left', 'bottom-right').
            placeholder: Placeholder text for the search input.
            collapsed: Whether the control starts collapsed (icon only).
            fly_to_zoom: Zoom level to fly to when selecting a result.
            show_marker: Whether to add a marker at the selected location.
            marker_color: Color of the result marker.
            **kwargs: Additional SearchControl options.

        Example:
            >>> m = Map()
            >>> m.add_search_control(position="top-left", fly_to_zoom=12)
        """
        self._validate_position(position)
        self.call_js_method(
            "addSearchControl",
            position=position,
            placeholder=placeholder,
            collapsed=collapsed,
            flyToZoom=fly_to_zoom,
            showMarker=show_marker,
            markerColor=marker_color,
            **kwargs,
        )
        self._controls = {
            **self._controls,
            "search-control": {
                "type": "search-control",
                "position": position,
                "collapsed": collapsed,
            },
        }

    def remove_search_control(self) -> None:
        """Remove the search/geocoder control from the map."""
        self.call_js_method("removeSearchControl")
        if "search-control" in self._controls:
            controls = dict(self._controls)
            del controls["search-control"]
            self._controls = controls

    # -------------------------------------------------------------------------
    # Measurement Tools
    # -------------------------------------------------------------------------

    def add_measure_control(
        self,
        position: str = "top-right",
        collapsed: bool = True,
        default_mode: str = "distance",
        distance_unit: str = "kilometers",
        area_unit: str = "square-kilometers",
        line_color: str = "#3b82f6",
        fill_color: str = "rgba(59, 130, 246, 0.2)",
        **kwargs,
    ) -> None:
        """Add a measurement control for distances and areas.

        Provides tools for measuring distances (polylines) and areas
        (polygons) interactively on the map.

        Args:
            position: Control position ('top-left', 'top-right',
                'bottom-left', 'bottom-right').
            collapsed: Whether the control starts collapsed.
            default_mode: Default measurement mode ('distance' or 'area').
            distance_unit: Distance unit ('kilometers', 'miles', 'meters',
                'feet', 'nautical-miles').
            area_unit: Area unit ('square-kilometers', 'square-miles',
                'square-meters', 'hectares', 'acres').
            line_color: Line color for distance measurements.
            fill_color: Fill color for area measurements.
            **kwargs: Additional MeasureControl options.

        Example:
            >>> m = Map()
            >>> m.add_measure_control(
            ...     default_mode="distance",
            ...     distance_unit="miles",
            ... )
        """
        self._validate_position(position)
        self.call_js_method(
            "addMeasureControl",
            position=position,
            collapsed=collapsed,
            defaultMode=default_mode,
            distanceUnit=distance_unit,
            areaUnit=area_unit,
            lineColor=line_color,
            fillColor=fill_color,
            **kwargs,
        )
        self._controls = {
            **self._controls,
            "measure-control": {
                "type": "measure-control",
                "position": position,
                "collapsed": collapsed,
            },
        }

    def remove_measure_control(self) -> None:
        """Remove the measurement control from the map."""
        self.call_js_method("removeMeasureControl")
        if "measure-control" in self._controls:
            controls = dict(self._controls)
            del controls["measure-control"]
            self._controls = controls

    # -------------------------------------------------------------------------
    # Print / Export Control
    # -------------------------------------------------------------------------

    def add_print_control(
        self,
        position: str = "top-right",
        collapsed: bool = True,
        format: str = "png",
        filename: str = "map-export",
        include_north_arrow: bool = False,
        include_scale_bar: bool = False,
        **kwargs,
    ) -> None:
        """Add a print/export control for saving the map as an image.

        Provides an interactive panel for exporting the current map view
        as PNG, JPEG, or PDF files.

        Args:
            position: Control position ('top-left', 'top-right',
                'bottom-left', 'bottom-right').
            collapsed: Whether the control starts collapsed.
            format: Default image format ('png', 'jpeg', 'pdf').
            filename: Default filename (without extension).
            include_north_arrow: Whether to include a north arrow by default.
            include_scale_bar: Whether to include a scale bar by default.
            **kwargs: Additional PrintControl options.

        Example:
            >>> m = Map()
            >>> m.add_print_control(
            ...     format="png",
            ...     filename="my-map",
            ...     include_scale_bar=True,
            ... )
        """
        self._validate_position(position)
        self.call_js_method(
            "addPrintControl",
            position=position,
            collapsed=collapsed,
            format=format,
            filename=filename,
            includeNorthArrow=include_north_arrow,
            includeScaleBar=include_scale_bar,
            **kwargs,
        )
        self._controls = {
            **self._controls,
            "print-control": {
                "type": "print-control",
                "position": position,
                "collapsed": collapsed,
            },
        }

    def remove_print_control(self) -> None:
        """Remove the print/export control from the map."""
        self.call_js_method("removePrintControl")
        if "print-control" in self._controls:
            controls = dict(self._controls)
            del controls["print-control"]
            self._controls = controls

    # -------------------------------------------------------------------------
    # FlatGeobuf Layer
    # -------------------------------------------------------------------------

    def add_flatgeobuf(
        self,
        url: str,
        name: Optional[str] = None,
        layer_type: Optional[str] = None,
        paint: Optional[Dict] = None,
        fit_bounds: bool = True,
        **kwargs,
    ) -> None:
        """Add a FlatGeobuf layer from a URL.

        Streams and renders cloud-native FlatGeobuf vector data directly
        in the browser without downloading the entire file.

        Args:
            url: URL to the FlatGeobuf file.
            name: Layer name. If None, auto-generated.
            layer_type: MapLibre layer type ('circle', 'line', 'fill').
                If None, inferred from geometry type.
            paint: MapLibre paint properties. If None, defaults are used.
            fit_bounds: Whether to fit map to data bounds.
            **kwargs: Additional layer options.

        Example:
            >>> m = Map()
            >>> m.add_flatgeobuf(
            ...     "https://flatgeobuf.org/test/data/UScounties.fgb",
            ...     name="counties",
            ...     paint={"fill-color": "#088", "fill-opacity": 0.5},
            ... )
        """
        layer_id = name or f"flatgeobuf-{len(self._layers)}"

        self.call_js_method(
            "addFlatGeobuf",
            url=url,
            name=layer_id,
            layerType=layer_type,
            paint=paint,
            fitBounds=fit_bounds,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "flatgeobuf",
                "url": url,
            },
        }
        self._add_to_layer_dict(layer_id, "Vector")

    def remove_flatgeobuf(self, name: str) -> None:
        """Remove a FlatGeobuf layer from the map.

        Args:
            name: The layer identifier to remove.
        """
        if name in self._layers:
            layers = dict(self._layers)
            del layers[name]
            self._layers = layers
        self._remove_from_layer_dict(name)
        self.call_js_method("removeFlatGeobuf", name=name)

    def _process_deck_data(self, data: Any) -> Any:
        """Process data for deck.gl layers.

        Handles GeoDataFrame, file paths, GeoJSON, and list of dicts.

        Args:
            data: Input data in various formats.

        Returns:
            Processed data suitable for deck.gl layers.
        """
        # Handle GeoDataFrame
        if hasattr(data, "__geo_interface__"):
            return data.__geo_interface__

        # Handle file paths
        if isinstance(data, (str, Path)):
            path = Path(data)
            if path.exists():
                try:
                    import geopandas as gpd

                    gdf = gpd.read_file(path)
                    return gdf.__geo_interface__
                except ImportError:
                    pass

        # Return as-is for lists, dicts, etc.
        return data

    # -------------------------------------------------------------------------
    # Layer Management
    # -------------------------------------------------------------------------

    def add_layer(
        self,
        layer_id: str,
        layer_type: str,
        source: Union[str, Dict],
        paint: Optional[Dict] = None,
        layout: Optional[Dict] = None,
        before_id: Optional[str] = None,
        **kwargs,
    ) -> None:
        """Add a generic layer to the map.

        Args:
            layer_id: Unique layer identifier
            layer_type: MapLibre layer type
            source: Source ID or source configuration dict
            paint: Paint properties
            layout: Layout properties
            before_id: ID of layer to insert before
            **kwargs: Additional layer options
        """
        layer_config = {
            "id": layer_id,
            "type": layer_type,
            "paint": paint or {},
            "layout": layout or {},
            **kwargs,
        }

        if isinstance(source, str):
            layer_config["source"] = source
        else:
            source_id = f"{layer_id}-source"
            self._sources = {**self._sources, source_id: source}
            self.call_js_method("addSource", source_id, **source)
            layer_config["source"] = source_id

        self._layers = {**self._layers, layer_id: layer_config}
        self.call_js_method("addLayer", beforeId=before_id, **layer_config)
        # Determine category based on layer type
        layer_type = layer_config.get("type", "")
        if layer_type == "raster":
            self._add_to_layer_dict(layer_id, "Raster")
        else:
            self._add_to_layer_dict(layer_id, "Vector")

    def remove_layer(self, layer_id: str) -> None:
        """Remove a layer from the map.

        Args:
            layer_id: Layer identifier to remove
        """
        if layer_id in self._layers:
            layers = dict(self._layers)
            del layers[layer_id]
            self._layers = layers
        self._remove_from_layer_dict(layer_id)
        self.call_js_method("removeLayer", layer_id)

    def set_visibility(self, layer_id: str, visible: bool) -> None:
        """Set layer visibility.

        Args:
            layer_id: Layer identifier
            visible: Whether layer should be visible
        """
        self.call_js_method("setVisibility", layer_id, visible)

    def set_opacity(self, layer_id: str, opacity: float) -> None:
        """Set layer opacity.

        Args:
            layer_id: Layer identifier
            opacity: Opacity value between 0 and 1
        """
        self._validate_opacity(opacity)
        self.call_js_method("setOpacity", layer_id, opacity)

    def set_paint_property(self, layer_id: str, property_name: str, value: Any) -> None:
        """Set a paint property for a layer.

        Args:
            layer_id: Layer identifier.
            property_name: Name of the paint property (e.g., 'fill-color').
            value: New value for the property.

        Example:
            >>> m.set_paint_property("my-layer", "fill-color", "#ff0000")
            >>> m.set_paint_property("my-layer", "fill-opacity", 0.5)
        """
        self.call_js_method("setPaintProperty", layer_id, property_name, value)

    def set_layout_property(
        self, layer_id: str, property_name: str, value: Any
    ) -> None:
        """Set a layout property for a layer.

        Args:
            layer_id: Layer identifier.
            property_name: Name of the layout property (e.g., 'visibility').
            value: New value for the property.

        Example:
            >>> m.set_layout_property("my-layer", "visibility", "none")
        """
        self.call_js_method("setLayoutProperty", layer_id, property_name, value)

    def move_layer(self, layer_id: str, before_id: Optional[str] = None) -> None:
        """Move a layer in the layer stack.

        Args:
            layer_id: Layer identifier to move.
            before_id: ID of layer to move before. If None, moves to top.

        Example:
            >>> m.move_layer("my-layer", "other-layer")  # Move before other-layer
            >>> m.move_layer("my-layer")  # Move to top
        """
        self.call_js_method("moveLayer", layer_id, before_id)

    def get_layer(self, layer_id: str) -> Optional[Dict]:
        """Get layer configuration by ID.

        Args:
            layer_id: Layer identifier.

        Returns:
            Layer configuration dict or None if not found.
        """
        return self._layers.get(layer_id)

    def get_layer_ids(self) -> List[str]:
        """Get list of all layer IDs.

        Returns:
            List of layer identifiers.
        """
        return list(self._layers.keys())

    def add_popup(
        self,
        layer_id: str,
        properties: Optional[List[str]] = None,
        template: Optional[str] = None,
        **kwargs,
    ) -> None:
        """Add popup on click for a layer.

        Configures a layer to show a popup when features are clicked.

        Args:
            layer_id: Layer identifier to add popup to.
            properties: List of property names to display. If None, shows all.
            template: Custom HTML template for popup content. Use {property_name}
                placeholders for values. If None, auto-generates table.
            **kwargs: Additional popup options (maxWidth, closeButton, etc.).

        Example:
            >>> m.add_vector(geojson, name="cities")
            >>> m.add_popup("cities", properties=["name", "population"])
            >>> # Or with custom template:
            >>> m.add_popup("cities", template="<h3>{name}</h3><p>Pop: {population}</p>")
        """
        self.call_js_method(
            "addPopup",
            layerId=layer_id,
            properties=properties,
            template=template,
            **kwargs,
        )

    # -------------------------------------------------------------------------
    # Terrain and Image Overlay Methods
    # -------------------------------------------------------------------------

    def add_3d_terrain(
        self,
        source: str = "terrarium",
        exaggeration: float = 1.0,
        **kwargs,
    ) -> None:
        """Enable 3D terrain visualization.

        MapLibre GL JS supports 3D terrain rendering using elevation data
        from various terrain tile sources.

        Args:
            source: Terrain source - 'terrarium' (AWS terrain tiles) or
                'mapbox' (requires Mapbox token) or custom terrain URL.
            exaggeration: Vertical exaggeration factor. Default 1.0.
            **kwargs: Additional terrain options.

        Example:
            >>> from anymap_ts import Map
            >>> m = Map(center=[-122.4, 37.8], zoom=12, pitch=60)
            >>> m.add_3d_terrain(exaggeration=1.5)
        """
        # Define terrain sources
        terrain_sources = {
            "terrarium": {
                "url": "https://s3.amazonaws.com/elevation-tiles-prod/terrarium/{z}/{x}/{y}.png",
                "encoding": "terrarium",
            },
            "mapbox": {
                "url": "mapbox://mapbox.mapbox-terrain-dem-v1",
                "encoding": "mapbox",
            },
        }

        if source in terrain_sources:
            terrain_config = terrain_sources[source]
        else:
            # Assume it's a custom URL
            terrain_config = {"url": source, "encoding": "terrarium"}

        self.call_js_method(
            "addTerrain",
            source=terrain_config,
            exaggeration=exaggeration,
            **kwargs,
        )

    def add_image_layer(
        self,
        url: str,
        coordinates: List[List[float]],
        name: Optional[str] = None,
        opacity: float = 1.0,
        **kwargs,
    ) -> None:
        """Add a georeferenced image overlay.

        Overlays an image on the map at specified geographic coordinates.

        Args:
            url: URL to the image file.
            coordinates: Four corner coordinates as [[lng, lat], ...] in order:
                top-left, top-right, bottom-right, bottom-left.
            name: Layer identifier. If None, auto-generated.
            opacity: Layer opacity (0-1).
            **kwargs: Additional layer options.

        Example:
            >>> from anymap_ts import Map
            >>> m = Map()
            >>> m.add_image_layer(
            ...     url="https://example.com/overlay.png",
            ...     coordinates=[
            ...         [-80.425, 46.437],  # top-left
            ...         [-71.516, 46.437],  # top-right
            ...         [-71.516, 37.936],  # bottom-right
            ...         [-80.425, 37.936],  # bottom-left
            ...     ]
            ... )
        """
        self._validate_opacity(opacity)
        layer_id = name or f"image-{len(self._layers)}"

        if len(coordinates) != 4:
            raise ValueError(
                "coordinates must have exactly 4 corner points "
                "[top-left, top-right, bottom-right, bottom-left]"
            )

        self.call_js_method(
            "addImageLayer",
            id=layer_id,
            url=url,
            coordinates=coordinates,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "image",
                "url": url,
                "coordinates": coordinates,
            },
        }
        self._add_to_layer_dict(layer_id, "Raster")

    # -------------------------------------------------------------------------
    # Controls
    # -------------------------------------------------------------------------

    def add_control(
        self,
        control_type: str,
        position: str = "top-right",
        **kwargs,
    ) -> None:
        """Add a map control.

        Args:
            control_type: Type of control ('navigation', 'scale', 'fullscreen', etc.)
            position: Control position
            **kwargs: Control-specific options
        """
        self.call_js_method("addControl", control_type, position=position, **kwargs)
        self._controls = {
            **self._controls,
            control_type: {"type": control_type, "position": position, **kwargs},
        }

    def remove_control(self, control_type: str) -> None:
        """Remove a map control.

        Args:
            control_type: Type of control to remove
        """
        self.call_js_method("removeControl", control_type)
        if control_type in self._controls:
            controls = dict(self._controls)
            del controls[control_type]
            self._controls = controls

    def add_layer_control(
        self,
        layers: Optional[List[str]] = None,
        position: str = "top-right",
        collapsed: bool = True,
    ) -> None:
        """Add a layer visibility control.

        Uses maplibre-gl-layer-control for layer toggling and opacity.

        Args:
            layers: List of layer IDs to include (None = all layers)
            position: Control position
            collapsed: Whether control starts collapsed
        """
        if layers is None:
            layers = list(self._layers.keys())

        self.call_js_method(
            "addLayerControl",
            layers=layers,
            position=position,
            collapsed=collapsed,
        )
        self._controls = {
            **self._controls,
            "layer-control": {
                "layers": layers,
                "position": position,
                "collapsed": collapsed,
            },
        }

    def add_legend(
        self,
        title: str,
        labels: List[str],
        colors: List[str],
        position: str = "bottom-right",
        opacity: float = 1.0,
        legend_id: Optional[str] = None,
        **kwargs,
    ) -> None:
        """Add a floating legend control to the map.

        Creates a custom legend control with colored boxes and labels that
        floats over the map in the specified position.

        Args:
            title: Legend title text
            labels: List of label strings for each legend item
            colors: List of hex color strings (e.g., ['#ff0000', '#00ff00', '#0000ff'])
            position: Legend position ('top-left', 'top-right', 'bottom-left', 'bottom-right')
            opacity: Legend background opacity (0-1)
            legend_id: Custom legend identifier (auto-generated if None)
            **kwargs: Additional legend styling options

        Example:
            >>> from anymap_ts import Map
            >>> m = Map()
            >>> m.add_legend(
            ...     title="Land Cover",
            ...     labels=["Forest", "Water", "Urban"],
            ...     colors=["#228B22", "#0000FF", "#808080"],
            ...     position="top-left"
            ... )
        """
        if len(labels) != len(colors):
            raise ValueError("Number of labels must match number of colors")

        # Validate position
        self._validate_position(position)

        # Validate colors (basic hex color check)
        for i, color in enumerate(colors):
            if not isinstance(color, str) or not color.startswith("#"):
                raise ValueError(
                    f"Color at index {i} must be a hex color string (e.g., '#ff0000')"
                )

        legend_id = (
            legend_id
            or f"legend-{len([k for k in self._controls.keys() if k.startswith('legend')])}"
        )

        # Prepare legend data
        legend_items = []
        for label, color in zip(labels, colors):
            legend_items.append(
                {
                    "label": label,
                    "color": color,
                }
            )

        # Call JavaScript method to add legend
        self.call_js_method(
            "addLegend",
            id=legend_id,
            title=title,
            items=legend_items,
            position=position,
            opacity=opacity,
            **kwargs,
        )

        # Track legend control
        self._controls = {
            **self._controls,
            legend_id: {
                "type": "legend",
                "title": title,
                "labels": labels,
                "colors": colors,
                "position": position,
                "opacity": opacity,
            },
        }

    def remove_legend(self, legend_id: Optional[str] = None) -> None:
        """Remove a legend control from the map.

        Args:
            legend_id: Legend identifier to remove. If None, removes all legends.
        """
        if legend_id is None:
            # Remove all legends - create a copy of keys before iterating
            legend_keys = [k for k in self._controls.keys() if k.startswith("legend")]
            for key in legend_keys:
                self.call_js_method("removeLegend", key)
            # Rebuild controls dict without legend keys
            self._controls = {
                k: v for k, v in self._controls.items() if not k.startswith("legend")
            }
        else:
            self.call_js_method("removeLegend", legend_id)
            if legend_id in self._controls:
                controls = dict(self._controls)
                del controls[legend_id]
                self._controls = controls

    def update_legend(
        self,
        legend_id: str,
        title: Optional[str] = None,
        labels: Optional[List[str]] = None,
        colors: Optional[List[str]] = None,
        opacity: Optional[float] = None,
        **kwargs,
    ) -> None:
        """Update an existing legend's properties.

        Args:
            legend_id: Legend identifier to update
            title: New title (if provided)
            labels: New labels list (if provided)
            colors: New colors list (if provided)
            opacity: New opacity (if provided)
            **kwargs: Additional properties to update
        """
        if legend_id not in self._controls:
            raise ValueError(f"Legend '{legend_id}' not found")

        update_params = {"id": legend_id}

        if title is not None:
            update_params["title"] = title
            self._controls[legend_id]["title"] = title

        if labels is not None and colors is not None:
            if len(labels) != len(colors):
                raise ValueError("Number of labels must match number of colors")

            legend_items = [
                {"label": label, "color": color} for label, color in zip(labels, colors)
            ]
            update_params["items"] = legend_items
            self._controls[legend_id]["labels"] = labels
            self._controls[legend_id]["colors"] = colors

        elif labels is not None or colors is not None:
            raise ValueError("Both labels and colors must be provided together")

        if opacity is not None:
            update_params["opacity"] = opacity
            self._controls[legend_id]["opacity"] = opacity

        update_params.update(kwargs)
        self.call_js_method("updateLegend", **update_params)

    # -------------------------------------------------------------------------
    # Drawing
    # -------------------------------------------------------------------------

    def add_draw_control(
        self,
        position: str = "top-right",
        draw_modes: Optional[List[str]] = None,
        edit_modes: Optional[List[str]] = None,
        collapsed: bool = False,
        **kwargs,
    ) -> None:
        """Add a drawing control using maplibre-gl-geo-editor.

        Args:
            position: Control position
            draw_modes: Drawing modes to enable (e.g., ['polygon', 'line', 'marker'])
            edit_modes: Edit modes to enable (e.g., ['select', 'drag', 'delete'])
            collapsed: Whether control starts collapsed
            **kwargs: Additional geo-editor options
        """
        if draw_modes is None:
            draw_modes = ["polygon", "line", "rectangle", "circle", "marker"]
        if edit_modes is None:
            edit_modes = ["select", "drag", "change", "rotate", "delete"]

        self.call_js_method(
            "addDrawControl",
            position=position,
            drawModes=draw_modes,
            editModes=edit_modes,
            collapsed=collapsed,
            **kwargs,
        )
        self._controls = {
            **self._controls,
            "draw-control": {
                "position": position,
                "drawModes": draw_modes,
                "editModes": edit_modes,
            },
        }

    def get_draw_data(self) -> Dict:
        """Get the current drawn features as GeoJSON.

        Returns:
            GeoJSON FeatureCollection of drawn features
        """
        self.call_js_method("getDrawData")
        # Small delay to allow JS to update the trait
        import time

        time.sleep(0.1)
        return self._draw_data or {"type": "FeatureCollection", "features": []}

    @property
    def draw_data(self) -> Dict:
        """Property to access current draw data."""
        return self._draw_data or {"type": "FeatureCollection", "features": []}

    def load_draw_data(self, geojson: Dict) -> None:
        """Load GeoJSON features into the drawing layer.

        Args:
            geojson: GeoJSON FeatureCollection to load
        """
        self._draw_data = geojson
        self.call_js_method("loadDrawData", geojson)

    def clear_draw_data(self) -> None:
        """Clear all drawn features."""
        self._draw_data = {"type": "FeatureCollection", "features": []}
        self.call_js_method("clearDrawData")

    def save_draw_data(
        self,
        filepath: Union[str, Path],
        driver: Optional[str] = None,
    ) -> None:
        """Save drawn features to a file.

        Args:
            filepath: Path to save file
            driver: Output driver (auto-detected from extension if not provided)

        Raises:
            ImportError: If geopandas is not installed
        """
        try:
            import geopandas as gpd
        except ImportError:
            raise ImportError(
                "geopandas is required to save draw data. "
                "Install with: pip install anymap-ts[vector]"
            )

        data = self.get_draw_data()
        if not data.get("features"):
            print("No features to save")
            return

        gdf = gpd.GeoDataFrame.from_features(data["features"])
        filepath = Path(filepath)

        # Infer driver from extension
        if driver is None:
            ext = filepath.suffix.lower()
            driver_map = {
                ".geojson": "GeoJSON",
                ".json": "GeoJSON",
                ".shp": "ESRI Shapefile",
                ".gpkg": "GPKG",
            }
            driver = driver_map.get(ext, "GeoJSON")

        gdf.to_file(filepath, driver=driver)

    # -------------------------------------------------------------------------
    # GeoJSON Clustering
    # -------------------------------------------------------------------------

    def add_cluster_layer(
        self,
        data: Any,
        cluster_radius: int = 50,
        cluster_max_zoom: int = 14,
        cluster_colors: Optional[List[str]] = None,
        cluster_steps: Optional[List[int]] = None,
        cluster_min_radius: int = 15,
        cluster_max_radius: int = 30,
        unclustered_color: str = "#11b4da",
        unclustered_radius: int = 8,
        show_cluster_count: bool = True,
        name: Optional[str] = None,
        zoom_on_click: bool = True,
        fit_bounds: bool = True,
        **kwargs,
    ) -> str:
        """Add a clustered point layer with automatic grouping.

        Creates a point layer that automatically clusters nearby points at
        lower zoom levels. Clicking on clusters zooms in to expand them.

        Args:
            data: Point data - GeoJSON, GeoDataFrame, file path, or URL.
            cluster_radius: Radius of each cluster when grouping points (pixels).
            cluster_max_zoom: Max zoom level to cluster points (above this, all
                points are shown individually).
            cluster_colors: List of colors for cluster circles by size.
                Default: ["#51bbd6", "#f1f075", "#f28cb1"].
            cluster_steps: Point count thresholds for color changes.
                Default: [100, 750]. Must have len(cluster_colors) - 1 values.
            cluster_min_radius: Minimum cluster circle radius in pixels.
            cluster_max_radius: Maximum cluster circle radius in pixels.
            unclustered_color: Color for individual (unclustered) points.
            unclustered_radius: Radius for individual points in pixels.
            show_cluster_count: Whether to show point count in clusters.
            name: Layer identifier. If None, auto-generated.
            zoom_on_click: Whether clicking clusters zooms in to expand them.
            fit_bounds: Whether to fit map to data bounds.
            **kwargs: Additional options.

        Returns:
            The layer identifier.

        Example:
            >>> from anymap_ts import Map
            >>> m = Map()
            >>> m.add_cluster_layer(
            ...     "earthquakes.geojson",
            ...     cluster_radius=80,
            ...     cluster_colors=["#00ff00", "#ffff00", "#ff0000"],
            ...     cluster_steps=[50, 500],
            ... )
        """
        layer_id = name or f"cluster-{len(self._layers)}"

        # Default colors and steps
        if cluster_colors is None:
            cluster_colors = ["#51bbd6", "#f1f075", "#f28cb1"]
        if cluster_steps is None:
            cluster_steps = [100, 750]

        # Validate steps vs colors
        if len(cluster_steps) != len(cluster_colors) - 1:
            raise ValueError(
                f"cluster_steps must have {len(cluster_colors) - 1} values "
                f"(one less than cluster_colors), got {len(cluster_steps)}"
            )

        # Convert data to GeoJSON
        geojson = to_geojson(data)

        # Handle URL data - fetch GeoJSON
        if geojson.get("type") == "url":
            url = geojson["url"]
            geojson = fetch_geojson(url)

        # Get bounds
        bounds = get_bounds(geojson) if fit_bounds else None

        self.call_js_method(
            "addClusterLayer",
            data=geojson,
            name=layer_id,
            clusterRadius=cluster_radius,
            clusterMaxZoom=cluster_max_zoom,
            clusterColors=cluster_colors,
            clusterSteps=cluster_steps,
            clusterMinRadius=cluster_min_radius,
            clusterMaxRadius=cluster_max_radius,
            unclusteredColor=unclustered_color,
            unclusteredRadius=unclustered_radius,
            showClusterCount=show_cluster_count,
            zoomOnClick=zoom_on_click,
            fitBounds=fit_bounds,
            bounds=bounds,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "cluster",
                "source": f"{layer_id}-source",
            },
        }
        self._add_to_layer_dict(layer_id, "Vector")
        return layer_id

    def remove_cluster_layer(self, layer_id: str) -> None:
        """Remove a cluster layer and all its sublayers.

        Args:
            layer_id: Layer identifier to remove.
        """
        self._remove_layer_internal(layer_id, "removeClusterLayer")

    # -------------------------------------------------------------------------
    # Choropleth Maps
    # -------------------------------------------------------------------------

    def add_choropleth(
        self,
        data: Any,
        column: str,
        cmap: str = "viridis",
        classification: str = "quantile",
        k: int = 5,
        breaks: Optional[List[float]] = None,
        fill_opacity: float = 0.7,
        line_color: str = "#000000",
        line_width: float = 1,
        legend: bool = True,
        legend_title: Optional[str] = None,
        hover: bool = True,
        layer_id: Optional[str] = None,
        fit_bounds: bool = True,
        **kwargs,
    ) -> None:
        """Add a choropleth (thematic) map layer with automatic classification.

        Choropleth maps use color gradients to visualize data values across
        geographic areas. This method automatically classifies data and applies
        appropriate colors.

        Args:
            data: Polygon data - GeoJSON, GeoDataFrame, file path, or URL.
            column: Property name to visualize (must be numeric).
            cmap: Colormap name. Any matplotlib colormap is supported when
                matplotlib is installed. Common options include:
                - Sequential: 'viridis', 'plasma', 'inferno', 'magma', 'cividis',
                  'Blues', 'Greens', 'Reds', 'Oranges', 'Purples', 'Greys'
                - Diverging: 'RdBu', 'RdYlGn', 'RdYlBu', 'Spectral', 'coolwarm'
                - Qualitative: 'Set1', 'Set2', 'Set3', 'Paired', 'tab10', 'tab20'
                See: https://matplotlib.org/stable/gallery/color/colormap_reference.html
            classification: Classification method:
                - 'quantile': Equal number of features per class
                - 'equal_interval': Equal value ranges
                - 'natural_breaks': Jenks natural breaks (requires jenkspy)
                - 'manual': Use custom breaks
            k: Number of classes (ignored if classification='manual').
            breaks: Custom break values for 'manual' classification.
                Must have k+1 values defining class boundaries.
            fill_opacity: Polygon fill opacity (0-1).
            line_color: Polygon outline color.
            line_width: Polygon outline width.
            legend: Whether to add a legend.
            legend_title: Legend title. Defaults to column name.
            hover: Whether to enable hover highlight effect.
            layer_id: Layer identifier. If None, auto-generated.
            fit_bounds: Whether to fit map to data bounds.
            **kwargs: Additional layer options.

        Example:
            >>> from anymap_ts import Map
            >>> m = Map()
            >>> m.add_choropleth(
            ...     "us_states.geojson",
            ...     column="population",
            ...     cmap="YlOrRd",
            ...     classification="quantile",
            ...     k=5,
            ...     legend_title="Population"
            ... )
        """
        from .utils import (
            get_choropleth_colors,
            compute_breaks,
            build_step_expression,
        )

        layer_name = layer_id or f"choropleth-{len(self._layers)}"

        # Convert data to GeoJSON
        geojson = to_geojson(data)

        # Handle URL data - fetch GeoJSON
        if geojson.get("type") == "url":
            url = geojson["url"]
            geojson = fetch_geojson(url)

        # Extract values for classification
        features = geojson.get("features", [])
        values = []
        for feature in features:
            props = feature.get("properties", {})
            val = props.get(column)
            if val is not None:
                try:
                    values.append(float(val))
                except (TypeError, ValueError):
                    pass

        if not values:
            raise ValueError(f"No valid numeric values found for column '{column}'")

        # Compute breaks
        computed_breaks = compute_breaks(values, classification, k, breaks)

        # Get colors
        colors = get_choropleth_colors(cmap, k)

        # Build step expression for MapLibre
        step_expr = build_step_expression(column, computed_breaks, colors)

        # Get bounds
        bounds = get_bounds(geojson) if fit_bounds else None

        self.call_js_method(
            "addChoropleth",
            data=geojson,
            name=layer_name,
            column=column,
            stepExpression=step_expr,
            fillOpacity=fill_opacity,
            lineColor=line_color,
            lineWidth=line_width,
            hover=hover,
            fitBounds=fit_bounds,
            bounds=bounds,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_name: {
                "id": layer_name,
                "type": "choropleth",
                "source": f"{layer_name}-source",
                "column": column,
            },
        }
        self._add_to_layer_dict(layer_name, "Vector")

        # Add legend
        if legend:
            title = legend_title or column
            # Create labels from breaks
            labels = []
            for i in range(len(computed_breaks) - 1):
                low = computed_breaks[i]
                high = computed_breaks[i + 1]
                if i == len(computed_breaks) - 2:
                    labels.append(f"{low:.1f} - {high:.1f}")
                else:
                    labels.append(f"{low:.1f} - {high:.1f}")

            self.add_legend(
                title=title,
                labels=labels,
                colors=colors,
                position="bottom-right",
            )

    # -------------------------------------------------------------------------
    # 3D Buildings
    # -------------------------------------------------------------------------

    def add_3d_buildings(
        self,
        source: str = "openmaptiles",
        min_zoom: float = 14,
        fill_extrusion_color: str = "#aaa",
        fill_extrusion_opacity: float = 0.6,
        height_property: str = "render_height",
        base_property: str = "render_min_height",
        layer_id: Optional[str] = None,
        **kwargs,
    ) -> None:
        """Add 3D building extrusions from vector tiles.

        Creates 3D building visualizations using fill-extrusion layers.
        Works best with vector tile styles that include building data.

        Note:
            This feature requires a map style with vector tile building data.
            Recommended styles:
            - MapTiler styles (requires API key)
            - OpenFreeMap: "https://tiles.openfreemap.org/styles/liberty"
            - Protomaps styles

            CartoDB raster styles (Positron, DarkMatter) do NOT have building
            data. For those, the method will attempt to add OpenFreeMap tiles
            as a source, but results may vary.

        Args:
            source: Building source identifier. Usually auto-detected from
                the map style.
            min_zoom: Minimum zoom level to show buildings (default: 14).
            fill_extrusion_color: Building color as hex string.
            fill_extrusion_opacity: Building opacity (0-1).
            height_property: Property name for building height in the
                vector tiles (default: 'render_height').
            base_property: Property name for building base height
                (default: 'render_min_height').
            layer_id: Layer identifier. If None, uses '3d-buildings'.
            **kwargs: Additional layer options.

        Example:
            >>> from anymap_ts import Map
            >>> # Use a vector style with building data
            >>> m = Map(
            ...     center=[-74.0060, 40.7128],
            ...     zoom=15,
            ...     pitch=60,
            ...     style="https://tiles.openfreemap.org/styles/liberty"
            ... )
            >>> m.add_3d_buildings(
            ...     fill_extrusion_color="#4682B4",
            ...     fill_extrusion_opacity=0.8
            ... )
        """
        layer_name = layer_id or "3d-buildings"

        self.call_js_method(
            "add3DBuildings",
            source=source,
            minZoom=min_zoom,
            fillExtrusionColor=fill_extrusion_color,
            fillExtrusionOpacity=fill_extrusion_opacity,
            heightProperty=height_property,
            baseProperty=base_property,
            layerId=layer_name,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_name: {
                "id": layer_name,
                "type": "fill-extrusion",
            },
        }
        self._add_to_layer_dict(layer_name, "Vector")

    # -------------------------------------------------------------------------
    # Route Animation
    # -------------------------------------------------------------------------

    def animate_along_route(
        self,
        route: Any,
        duration: int = 10000,
        loop: bool = True,
        marker_color: str = "#3388ff",
        marker_size: float = 1.0,
        show_trail: bool = False,
        trail_color: str = "#3388ff",
        trail_width: float = 3,
        animation_id: Optional[str] = None,
        **kwargs,
    ) -> str:
        """Animate a marker along a route.

        Creates an animated marker that moves along the specified route line.

        Args:
            route: Route data - LineString GeoJSON, list of coordinates,
                GeoDataFrame, or file path.
            duration: Animation duration in milliseconds.
            loop: Whether to loop the animation.
            marker_color: Marker color.
            marker_size: Marker size multiplier.
            show_trail: Whether to show a trail behind the marker.
            trail_color: Trail line color.
            trail_width: Trail line width.
            animation_id: Animation identifier. If None, auto-generated.
            **kwargs: Additional animation options.

        Returns:
            The animation identifier.

        Example:
            >>> from anymap_ts import Map
            >>> m = Map()
            >>> coords = [[-122.4, 37.8], [-122.3, 37.7], [-122.2, 37.8]]
            >>> anim_id = m.animate_along_route(coords, duration=5000, loop=True)
        """
        anim_id = animation_id or f"animation-{len(self._layers)}"

        # Convert route to coordinates list
        if isinstance(route, list) and len(route) > 0:
            if isinstance(route[0], (list, tuple)):
                # Already a list of coordinates
                coordinates = route
            else:
                raise ValueError("Route list must contain coordinate pairs")
        elif isinstance(route, dict):
            # GeoJSON
            if route.get("type") == "LineString":
                coordinates = route.get("coordinates", [])
            elif route.get("type") == "Feature":
                geometry = route.get("geometry", {})
                if geometry.get("type") == "LineString":
                    coordinates = geometry.get("coordinates", [])
                else:
                    raise ValueError("Feature geometry must be LineString")
            elif route.get("type") == "FeatureCollection":
                features = route.get("features", [])
                if (
                    features
                    and features[0].get("geometry", {}).get("type") == "LineString"
                ):
                    coordinates = features[0]["geometry"]["coordinates"]
                else:
                    raise ValueError(
                        "FeatureCollection must contain LineString features"
                    )
            else:
                raise ValueError(
                    "GeoJSON must be LineString, Feature, or FeatureCollection"
                )
        else:
            # Try to convert using to_geojson
            geojson = to_geojson(route)
            if geojson.get("type") == "url":
                geojson = fetch_geojson(geojson["url"])
            # Extract coordinates from the converted geojson
            if geojson.get("type") == "FeatureCollection":
                features = geojson.get("features", [])
                if features:
                    coordinates = features[0].get("geometry", {}).get("coordinates", [])
                else:
                    raise ValueError("No features found in data")
            elif geojson.get("type") == "Feature":
                coordinates = geojson.get("geometry", {}).get("coordinates", [])
            else:
                coordinates = geojson.get("coordinates", [])

        if len(coordinates) < 2:
            raise ValueError("Route must have at least 2 points")

        self.call_js_method(
            "animateAlongRoute",
            id=anim_id,
            coordinates=coordinates,
            duration=duration,
            loop=loop,
            markerColor=marker_color,
            markerSize=marker_size,
            showTrail=show_trail,
            trailColor=trail_color,
            trailWidth=trail_width,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            anim_id: {
                "id": anim_id,
                "type": "animation",
            },
        }
        return anim_id

    def stop_animation(self, animation_id: str) -> None:
        """Stop a running animation.

        Args:
            animation_id: Animation identifier to stop.
        """
        self.call_js_method("stopAnimation", animation_id)
        if animation_id in self._layers:
            layers = dict(self._layers)
            del layers[animation_id]
            self._layers = layers

    def pause_animation(self, animation_id: str) -> None:
        """Pause a running animation.

        Args:
            animation_id: Animation identifier to pause.
        """
        self.call_js_method("pauseAnimation", animation_id)

    def resume_animation(self, animation_id: str) -> None:
        """Resume a paused animation.

        Args:
            animation_id: Animation identifier to resume.
        """
        self.call_js_method("resumeAnimation", animation_id)

    def set_animation_speed(self, animation_id: str, speed: float) -> None:
        """Set animation speed multiplier.

        Args:
            animation_id: Animation identifier.
            speed: Speed multiplier (1.0 = normal, 2.0 = double speed, etc.).
        """
        self.call_js_method("setAnimationSpeed", animation_id, speed)

    # -------------------------------------------------------------------------
    # Feature Hover Effect
    # -------------------------------------------------------------------------

    def add_hover_effect(
        self,
        layer_id: str,
        highlight_color: Optional[str] = None,
        highlight_opacity: Optional[float] = None,
        highlight_outline_width: float = 2,
        **kwargs,
    ) -> None:
        """Add hover highlight effect to an existing layer.

        When the mouse hovers over a feature, it will be highlighted with
        the specified styles.

        Args:
            layer_id: Layer identifier to add hover effect to.
            highlight_color: Override fill/line color on hover. If None,
                the original color is kept but opacity/outline changes.
            highlight_opacity: Override opacity on hover.
            highlight_outline_width: Outline width on hover.
            **kwargs: Additional hover effect options.

        Example:
            >>> from anymap_ts import Map
            >>> m = Map()
            >>> m.add_geojson("states.geojson", name="states")
            >>> m.add_hover_effect("states", highlight_opacity=0.9)
        """
        self.call_js_method(
            "addHoverEffect",
            layerId=layer_id,
            highlightColor=highlight_color,
            highlightOpacity=highlight_opacity,
            highlightOutlineWidth=highlight_outline_width,
            **kwargs,
        )

    # -------------------------------------------------------------------------
    # Sky & Fog
    # -------------------------------------------------------------------------

    def set_sky(
        self,
        sky_color: str = "#88C6FC",
        horizon_color: str = "#F0E4D4",
        fog_color: str = "#FFFFFF",
        sky_horizon_blend: float = 0.5,
        horizon_fog_blend: float = 0.5,
        fog_ground_blend: float = 0.5,
        atmosphere_blend: float = 0.8,
        **kwargs,
    ) -> None:
        """Set sky and fog atmospheric effects for 3D terrain visualization.

        MapLibre v5 unifies sky and fog into a single `map.setSky()` API.
        Best used with 3D terrain enabled.

        Args:
            sky_color: Color of the sky. Default is "#88C6FC".
            horizon_color: Color at the horizon. Default is "#F0E4D4".
            fog_color: Color of the fog. Default is "#FFFFFF".
            sky_horizon_blend: Blend between sky and horizon (0-1).
                Default is 0.5.
            horizon_fog_blend: Blend between horizon and fog (0-1).
                Default is 0.5.
            fog_ground_blend: Blend between fog and ground (0-1).
                Default is 0.5.
            atmosphere_blend: Intensity of the atmosphere effect (0-1).
                Default is 0.8.
            **kwargs: Additional sky options.

        Example:
            >>> from anymap_ts import Map
            >>> m = Map(center=[-122.4, 37.8], zoom=12, pitch=60)
            >>> m.add_3d_terrain(exaggeration=1.5)
            >>> m.set_sky()
        """
        self.call_js_method(
            "setSky",
            skyColor=sky_color,
            horizonColor=horizon_color,
            fogColor=fog_color,
            skyHorizonBlend=sky_horizon_blend,
            horizonFogBlend=horizon_fog_blend,
            fogGroundBlend=fog_ground_blend,
            atmosphereBlend=atmosphere_blend,
            **kwargs,
        )

    def remove_sky(self) -> None:
        """Remove sky and fog atmospheric effects from the map.

        Example:
            >>> m.remove_sky()
        """
        self.call_js_method("removeSky")

    # -------------------------------------------------------------------------
    # Feature Query/Filter
    # -------------------------------------------------------------------------

    def set_filter(
        self,
        layer_id: str,
        filter_expression: Optional[List] = None,
    ) -> None:
        """Set or clear a filter on a map layer.

        Uses MapLibre GL JS filter expressions to show/hide features.

        Args:
            layer_id: The layer to apply the filter to.
            filter_expression: A MapLibre filter expression (list).
                Pass None to clear the filter.

        Example:
            >>> m.set_filter("states-layer", [">=", ["get", "density"], 100])
            >>> m.set_filter("states-layer", None)  # Clear filter
        """
        self.call_js_method(
            "setFilter",
            layerId=layer_id,
            filter=filter_expression,
        )

    def query_rendered_features(
        self,
        geometry: Optional[Any] = None,
        layers: Optional[List[str]] = None,
        filter_expression: Optional[List] = None,
    ) -> Dict:
        """Query features currently rendered on the map.

        Results are stored in the `queried_features` property.

        Args:
            geometry: Optional point {x, y} or bounding box [[x1, y1], [x2, y2]]
                to limit the query area. If None, queries the entire viewport.
            layers: Optional list of layer IDs to query. If None, queries all
                layers.
            filter_expression: Optional MapLibre filter expression to further
                filter results.

        Returns:
            The current queried features dict (may not yet reflect this query
            if called immediately; use the `queried_features` property).

        Example:
            >>> m.query_rendered_features(layers=["states-layer"])
            >>> features = m.queried_features
        """
        kwargs: Dict[str, Any] = {}
        if geometry is not None:
            kwargs["geometry"] = geometry
        if layers is not None:
            kwargs["layers"] = layers
        if filter_expression is not None:
            kwargs["filter"] = filter_expression

        self.call_js_method("queryRenderedFeatures", **kwargs)
        return self._queried_features

    def query_source_features(
        self,
        source_id: str,
        source_layer: Optional[str] = None,
        filter_expression: Optional[List] = None,
    ) -> Dict:
        """Query features from a source, including features not currently visible.

        Results are stored in the `queried_features` property.

        Args:
            source_id: The source to query.
            source_layer: Optional source layer for vector tile sources.
            filter_expression: Optional MapLibre filter expression.

        Returns:
            The current queried features dict.

        Example:
            >>> m.query_source_features("states-source")
            >>> features = m.queried_features
        """
        kwargs: Dict[str, Any] = {"sourceId": source_id}
        if source_layer is not None:
            kwargs["sourceLayer"] = source_layer
        if filter_expression is not None:
            kwargs["filter"] = filter_expression

        self.call_js_method("querySourceFeatures", **kwargs)
        return self._queried_features

    @property
    def queried_features(self) -> Dict:
        """Get the most recent query results.

        Returns:
            A GeoJSON FeatureCollection dict with queried features.
        """
        return self._queried_features

    # -------------------------------------------------------------------------
    # Video Layer
    # -------------------------------------------------------------------------

    def add_video_layer(
        self,
        urls: List[str],
        coordinates: List[List[float]],
        name: Optional[str] = None,
        opacity: float = 1.0,
        **kwargs,
    ) -> None:
        """Add a georeferenced video overlay on the map.

        Args:
            urls: List of video URLs (provide multiple formats for browser
                compatibility, e.g., [".mp4", ".webm"]).
            coordinates: Four corner coordinates as [[lng, lat], ...] in order:
                top-left, top-right, bottom-right, bottom-left.
            name: Layer identifier. If None, auto-generated.
            opacity: Layer opacity (0-1). Default is 1.0.
            **kwargs: Additional layer options.

        Example:
            >>> m.add_video_layer(
            ...     urls=["https://example.com/video.mp4"],
            ...     coordinates=[
            ...         [-122.51596391658498, 37.56238816766053],
            ...         [-122.51467645489949, 37.56410183312965],
            ...         [-122.51309394645498, 37.563391708549425],
            ...         [-122.51423120498498, 37.56161849366671],
            ...     ],
            ... )
        """
        self._validate_opacity(opacity)
        layer_id = name or f"video-{len(self._layers)}"

        if len(coordinates) != 4:
            raise ValueError(
                "coordinates must have exactly 4 corner points "
                "[top-left, top-right, bottom-right, bottom-left]"
            )

        self.call_js_method(
            "addVideoLayer",
            id=layer_id,
            urls=urls,
            coordinates=coordinates,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {
                "id": layer_id,
                "type": "video",
                "source": f"{layer_id}-source",
            },
        }
        self._add_to_layer_dict(layer_id, "Raster")

    def remove_video_layer(self, name: str) -> None:
        """Remove a video layer from the map.

        Args:
            name: The layer identifier to remove.
        """
        if name in self._layers:
            layers = dict(self._layers)
            del layers[name]
            self._layers = layers
        self._remove_from_layer_dict(name)
        self.call_js_method("removeVideoLayer", id=name)

    def play_video(self, name: str) -> None:
        """Start playing a video layer.

        Args:
            name: The video layer identifier.
        """
        self.call_js_method("playVideo", id=name)

    def pause_video(self, name: str) -> None:
        """Pause a video layer.

        Args:
            name: The video layer identifier.
        """
        self.call_js_method("pauseVideo", id=name)

    def seek_video(self, name: str, time: float) -> None:
        """Seek to a specific time in a video layer.

        Args:
            name: The video layer identifier.
            time: Time in seconds to seek to.
        """
        self.call_js_method("seekVideo", id=name, time=time)

    # -------------------------------------------------------------------------
    # Split Map (Swipe/Compare)
    # -------------------------------------------------------------------------

    def add_split_map(
        self,
        left_layer: str,
        right_layer: str,
        position: int = 50,
    ) -> None:
        """Add a split map comparison view with a draggable divider.

        Creates a side-by-side comparison of two layers. The left side shows
        the left layer and the right side shows the right layer, with a
        draggable slider to adjust the split position.

        Args:
            left_layer: Layer ID for the left side.
            right_layer: Layer ID for the right side.
            position: Initial slider position as percentage (0-100).
                Default is 50 (middle).

        Note:
            Both layers must exist on the map before calling this method.
            Best suited for raster tile layers (e.g., satellite vs streets).

        Example:
            >>> m.add_tile_layer(
            ...     "https://mt1.google.com/vt/lyrs=s&x={x}&y={y}&z={z}",
            ...     name="satellite",
            ... )
            >>> m.add_tile_layer(
            ...     "https://tile.openstreetmap.org/{z}/{x}/{y}.png",
            ...     name="osm",
            ... )
            >>> m.add_split_map("satellite", "osm")
        """
        if not 0 <= position <= 100:
            raise ValueError(f"position must be between 0 and 100, got {position}")

        self.call_js_method(
            "addSplitMap",
            leftLayer=left_layer,
            rightLayer=right_layer,
            position=position,
        )

    def remove_split_map(self) -> None:
        """Remove the split map comparison view.

        Restores the map to normal single-view mode with all layers visible.
        """
        self.call_js_method("removeSplitMap")

    # -------------------------------------------------------------------------
    # Globe Projection (Section 3)
    # -------------------------------------------------------------------------

    def set_projection(self, projection: str = "mercator") -> None:
        """Set the map projection.

        MapLibre GL JS v4+ supports globe projection for a 3D globe view.

        Args:
            projection: Projection type. Supported values: 'mercator', 'globe'.

        Example:
            >>> m = MapLibreMap()
            >>> m.set_projection("globe")
        """
        self.call_js_method("setProjection", projection=projection)

    # -------------------------------------------------------------------------
    # Source Data Updates (Section 3)
    # -------------------------------------------------------------------------

    def update_geojson_source(self, source_id: str, data: Any) -> None:
        """Update the data of an existing GeoJSON source in place.

        This enables real-time/streaming data updates without removing
        and re-adding layers. Critical for live dashboards.

        Args:
            source_id: The ID of the GeoJSON source to update.
            data: New GeoJSON data (dict, GeoDataFrame, or URL string).

        Example:
            >>> m = MapLibreMap()
            >>> m.add_geojson("initial.geojson", name="points")
            >>> # Later, update with new data
            >>> m.update_geojson_source("points", new_geojson_data)
        """
        processed_data = self._process_deck_data(data)
        self.call_js_method(
            "updateGeoJSONSource",
            sourceId=source_id,
            data=processed_data,
        )

    # -------------------------------------------------------------------------
    # Custom Images & Sprites (Section 3)
    # -------------------------------------------------------------------------

    def add_image(self, name: str, url: str) -> None:
        """Load a custom icon image for use in symbol layers.

        Args:
            name: Name to reference this image in symbol layers.
            url: URL to the image file (PNG, JPEG, etc.).

        Example:
            >>> m = MapLibreMap()
            >>> m.add_image("custom-marker", "https://example.com/marker.png")
        """
        self.call_js_method("addMapImage", name=name, url=url)

    # -------------------------------------------------------------------------
    # Tooltip on Hover (Section 3 / Section 6)
    # -------------------------------------------------------------------------

    def add_tooltip(
        self,
        layer_id: str,
        template: Optional[str] = None,
        properties: Optional[List[str]] = None,
    ) -> None:
        """Add a tooltip that shows on feature hover.

        Shows formatted information when hovering over features in a layer.

        Args:
            layer_id: The ID of the layer to add tooltips to.
            template: HTML template with {property} placeholders.
                Example: "Name: {name}<br>Population: {pop}".
            properties: List of property names to display. If None and no
                template, all properties are shown.

        Example:
            >>> m = MapLibreMap()
            >>> m.add_geojson("data.geojson", name="cities")
            >>> m.add_tooltip("cities", template="<b>{name}</b><br>Pop: {population}")
        """
        self.call_js_method(
            "addTooltip",
            layerId=layer_id,
            template=template or "",
            properties=properties,
        )

    def remove_tooltip(self, layer_id: str) -> None:
        """Remove tooltip from a layer.

        Args:
            layer_id: The layer identifier.
        """
        self.call_js_method("removeTooltip", layerId=layer_id)

    # -------------------------------------------------------------------------
    # Coordinates Display Control (Section 3)
    # -------------------------------------------------------------------------

    def add_coordinates_control(
        self,
        position: str = "bottom-left",
        precision: int = 4,
    ) -> None:
        """Add a coordinates display showing cursor lat/lng.

        Args:
            position: Control position ('top-left', 'top-right',
                'bottom-left', 'bottom-right').
            precision: Number of decimal places for coordinates.

        Example:
            >>> m = MapLibreMap()
            >>> m.add_coordinates_control(position="bottom-left", precision=6)
        """
        self.call_js_method(
            "addCoordinatesControl",
            position=position,
            precision=precision,
        )

    def remove_coordinates_control(self) -> None:
        """Remove the coordinates display control."""
        self.call_js_method("removeCoordinatesControl")

    # -------------------------------------------------------------------------
    # Time Slider (Section 4)
    # -------------------------------------------------------------------------

    def add_time_slider(
        self,
        layer_id: str,
        property: str,
        min_value: float = 0,
        max_value: float = 100,
        step: float = 1,
        position: str = "bottom-left",
        label: str = "Time",
        auto_play: bool = False,
        interval: int = 500,
    ) -> None:
        """Add a time slider to filter data by a temporal property.

        Creates a slider control that filters layer features based on a
        numeric/temporal property, with optional auto-animation.

        Args:
            layer_id: Layer ID to filter.
            property: Property name to filter on.
            min_value: Minimum slider value.
            max_value: Maximum slider value.
            step: Step increment.
            position: Control position.
            label: Label text for the slider.
            auto_play: Whether to auto-animate through values.
            interval: Animation interval in milliseconds.

        Example:
            >>> m = MapLibreMap()
            >>> m.add_geojson("events.geojson", name="events")
            >>> m.add_time_slider("events", "year", min_value=2000, max_value=2024)
        """
        self.call_js_method(
            "addTimeSlider",
            layerId=layer_id,
            property=property,
            min=min_value,
            max=max_value,
            step=step,
            position=position,
            label=label,
            autoPlay=auto_play,
            interval=interval,
        )

    def remove_time_slider(self) -> None:
        """Remove the time slider control."""
        self.call_js_method("removeTimeSlider")

    # -------------------------------------------------------------------------
    # Swipe Map Comparison (Section 6)
    # -------------------------------------------------------------------------

    def add_swipe_map(self, left_layer: str, right_layer: str) -> None:
        """Add a drag-to-compare swipe control for two layers.

        Unlike split map which is side-by-side, swipe map overlays both
        layers and uses a draggable divider for before/after comparison.

        Args:
            left_layer: Layer ID for the left side.
            right_layer: Layer ID for the right side.

        Example:
            >>> m = MapLibreMap()
            >>> m.add_tile_layer("...", name="before")
            >>> m.add_tile_layer("...", name="after")
            >>> m.add_swipe_map("before", "after")
        """
        self.call_js_method(
            "addSwipeMap",
            leftLayer=left_layer,
            rightLayer=right_layer,
        )

    def remove_swipe_map(self) -> None:
        """Remove the swipe map comparison control."""
        self.call_js_method("removeSwipeMap")

    # -------------------------------------------------------------------------
    # Opacity Slider (Section 6)
    # -------------------------------------------------------------------------

    def add_opacity_slider(
        self,
        layer_id: str,
        position: str = "top-right",
        label: Optional[str] = None,
    ) -> None:
        """Add a UI slider to control layer opacity.

        Args:
            layer_id: Layer ID to control opacity for.
            position: Control position.
            label: Label text. Defaults to layer_id.

        Example:
            >>> m = MapLibreMap()
            >>> m.add_tile_layer("...", name="satellite")
            >>> m.add_opacity_slider("satellite")
        """
        self.call_js_method(
            "addOpacitySlider",
            layerId=layer_id,
            position=position,
            label=label or layer_id,
        )

    def remove_opacity_slider(self, layer_id: str) -> None:
        """Remove the opacity slider for a layer.

        Args:
            layer_id: Layer identifier.
        """
        self.call_js_method("removeOpacitySlider", layerId=layer_id)

    # -------------------------------------------------------------------------
    # Style Switcher (Section 8)
    # -------------------------------------------------------------------------

    def add_style_switcher(
        self,
        styles: Dict[str, str],
        position: str = "top-right",
    ) -> None:
        """Add a dropdown to switch between map styles.

        Args:
            styles: Dict mapping style names to style URLs.
            position: Control position.

        Example:
            >>> m = MapLibreMap()
            >>> m.add_style_switcher({
            ...     "Light": "https://basemaps.cartocdn.com/gl/positron-gl-style/style.json",
            ...     "Dark": "https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json",
            ...     "Voyager": "https://basemaps.cartocdn.com/gl/voyager-gl-style/style.json",
            ... })
        """
        self.call_js_method(
            "addStyleSwitcher",
            styles=styles,
            position=position,
        )

    def remove_style_switcher(self) -> None:
        """Remove the style switcher control."""
        self.call_js_method("removeStyleSwitcher")

    # -------------------------------------------------------------------------
    # Data Export (Section 7)
    # -------------------------------------------------------------------------

    def get_visible_features(
        self,
        layers: Optional[List[str]] = None,
    ) -> Optional[Dict]:
        """Get all features currently visible in the viewport.

        This triggers a query to the JavaScript side. The result is
        returned asynchronously via the ``_queried_features`` trait.

        On the first call, the query is sent and ``None`` is returned
        because the JavaScript side has not yet responded. Run this
        method in one notebook cell, then read the result in the next
        cell (the event loop processes the response between cells).

        Args:
            layers: Optional list of layer IDs to query. If ``None``,
                queries all visible layers.

        Returns:
            GeoJSON FeatureCollection dict if results are available from
            a previous query, otherwise ``None``.

        Example:
            >>> # Cell 1 – trigger the query
            >>> m.get_visible_features(layers=["my-layer"])
            >>> # Cell 2 – read the result
            >>> m.get_visible_features()
        """
        if layers is not None:
            self.call_js_method("getVisibleFeatures", layers=layers)
        features = self._queried_features
        if features and "data" in features:
            return features["data"]
        return None

    def to_geojson(self, layer_id: Optional[str] = None) -> Optional[Dict]:
        """Get layer data as GeoJSON.

        This triggers a query to the JavaScript side. The result is
        returned asynchronously via the ``_queried_features`` trait.

        On the first call with a ``layer_id``, the query is sent and
        ``None`` is returned. Run this method in one notebook cell,
        then call ``to_geojson()`` (without arguments) in the next cell
        to read the result.

        Args:
            layer_id: Source/layer ID to export. If ``None``, returns
                previously queried features.

        Returns:
            GeoJSON FeatureCollection dict, or ``None`` if not yet
            available.

        Example:
            >>> # Cell 1 – trigger the query
            >>> m.to_geojson("my-data")
            >>> # Cell 2 – read the result
            >>> result = m.to_geojson()
        """
        if layer_id:
            self.call_js_method("getLayerData", sourceId=layer_id)
        features = self._queried_features
        if features and "data" in features:
            return features["data"]
        return None

    def to_geopandas(self, layer_id: Optional[str] = None) -> Any:
        """Get layer data as a GeoDataFrame.

        Requires geopandas to be installed. Works the same as
        :meth:`to_geojson` – trigger with a ``layer_id`` in one cell,
        then call ``to_geopandas()`` in the next cell.

        Args:
            layer_id: Source/layer ID to export. If ``None``, returns
                previously queried features.

        Returns:
            GeoDataFrame, or ``None`` if data not available.

        Example:
            >>> # Cell 1 – trigger the query
            >>> m.to_geojson("my-data")
            >>> # Cell 2 – read the result
            >>> gdf = m.to_geopandas()
        """
        geojson = self.to_geojson(layer_id)
        if geojson is None:
            return None
        try:
            import geopandas as gpd

            return gpd.GeoDataFrame.from_features(geojson.get("features", []))
        except ImportError:
            raise ImportError("geopandas is required for to_geopandas()")

    # -------------------------------------------------------------------------
    # HTML Export
    # -------------------------------------------------------------------------

    def _generate_html_template(self) -> str:
        """Generate standalone HTML for the map."""
        template_path = Path(__file__).parent / "templates" / "maplibre.html"

        if not template_path.exists():
            raise FileNotFoundError(
                f"HTML template not found at {template_path}. "
                "Please ensure the templates directory is included in the package."
            )

        template = template_path.read_text(encoding="utf-8")

        # Serialize state
        state = {
            "center": self.center,
            "zoom": self.zoom,
            "style": self.style,
            "bearing": self.bearing,
            "pitch": self.pitch,
            "width": self.width,
            "height": self.height,
            "layers": self._layers,
            "sources": self._sources,
            "controls": self._controls,
            "js_calls": self._js_calls,
        }

        template = template.replace("{{state}}", json.dumps(state, indent=2))
        return template

draw_data: Dict property readonly

Property to access current draw data.

queried_features: Dict property readonly

Get the most recent query results.

Returns:

Type Description
Dict

A GeoJSON FeatureCollection dict with queried features.

__init__(self, center=(0.0, 0.0), zoom=2.0, width='100%', height='700px', style='https://basemaps.cartocdn.com/gl/positron-gl-style/style.json', bearing=0.0, pitch=0.0, max_pitch=85.0, projection='mercator', controls=None, **kwargs) special

Initialize a MapLibre map.

Parameters:

Name Type Description Default
center Tuple[float, float]

Map center as (longitude, latitude).

(0.0, 0.0)
zoom float

Initial zoom level.

2.0
width str

Map width as CSS string.

'100%'
height str

Map height as CSS string. Default is "700px".

'700px'
style Union[str, Dict]

MapLibre style URL or style object. Default is "https://basemaps.cartocdn.com/gl/positron-gl-style/style.json".

'https://basemaps.cartocdn.com/gl/positron-gl-style/style.json'
bearing float

Map bearing in degrees.

0.0
pitch float

Map pitch in degrees.

0.0
max_pitch float

Maximum pitch angle in degrees (default: 85).

85.0
projection str

Map projection. Supported values: 'mercator', 'globe'. Default is 'mercator'.

'mercator'
controls Optional[Dict[str, Any]]

Dict of controls to add. If None, defaults to {"layer-control": True, "control-grid": True}. Use {"layer-control": {"collapsed": True}} for custom options.

None
**kwargs

Additional widget arguments.

{}
Source code in anymap_ts/maplibre.py
def __init__(
    self,
    center: Tuple[float, float] = (0.0, 0.0),
    zoom: float = 2.0,
    width: str = "100%",
    height: str = "700px",
    style: Union[
        str, Dict
    ] = "https://basemaps.cartocdn.com/gl/positron-gl-style/style.json",
    bearing: float = 0.0,
    pitch: float = 0.0,
    max_pitch: float = 85.0,
    projection: str = "mercator",
    controls: Optional[Dict[str, Any]] = None,
    **kwargs,
):
    """Initialize a MapLibre map.

    Args:
        center: Map center as (longitude, latitude).
        zoom: Initial zoom level.
        width: Map width as CSS string.
        height: Map height as CSS string. Default is "700px".
        style: MapLibre style URL or style object. Default is "https://basemaps.cartocdn.com/gl/positron-gl-style/style.json".
        bearing: Map bearing in degrees.
        pitch: Map pitch in degrees.
        max_pitch: Maximum pitch angle in degrees (default: 85).
        projection: Map projection. Supported values: 'mercator', 'globe'.
            Default is 'mercator'.
        controls: Dict of controls to add. If None, defaults to
            {"layer-control": True, "control-grid": True}.
            Use {"layer-control": {"collapsed": True}} for custom options.
        **kwargs: Additional widget arguments.
    """
    # Handle style shortcuts
    if isinstance(style, str) and not style.startswith("http"):
        try:
            style = get_maplibre_style(style)
        except ValueError:
            pass  # Use as-is

    super().__init__(
        center=list(center),
        zoom=zoom,
        width=width,
        height=height,
        style=style,
        bearing=bearing,
        pitch=pitch,
        max_pitch=max_pitch,
        projection=projection,
        **kwargs,
    )

    # Initialize layer dictionary
    self._layer_dict = {"Background": []}

    # Add default controls
    if controls is None:
        controls = {
            "layer-control": True,
            "control-grid": True,
        }

    for control_name, config in controls.items():
        if config:
            if control_name == "layer-control":
                self.add_layer_control(
                    **(config if isinstance(config, dict) else {})
                )
            elif control_name == "control-grid":
                self.add_control_grid(
                    **(config if isinstance(config, dict) else {})
                )
            else:
                self.add_control(
                    control_name, **(config if isinstance(config, dict) else {})
                )

add_3d_buildings(self, source='openmaptiles', min_zoom=14, fill_extrusion_color='#aaa', fill_extrusion_opacity=0.6, height_property='render_height', base_property='render_min_height', layer_id=None, **kwargs)

Add 3D building extrusions from vector tiles.

Creates 3D building visualizations using fill-extrusion layers. Works best with vector tile styles that include building data.

Note

This feature requires a map style with vector tile building data. Recommended styles: - MapTiler styles (requires API key) - OpenFreeMap: "https://tiles.openfreemap.org/styles/liberty" - Protomaps styles

CartoDB raster styles (Positron, DarkMatter) do NOT have building data. For those, the method will attempt to add OpenFreeMap tiles as a source, but results may vary.

Parameters:

Name Type Description Default
source str

Building source identifier. Usually auto-detected from the map style.

'openmaptiles'
min_zoom float

Minimum zoom level to show buildings (default: 14).

14
fill_extrusion_color str

Building color as hex string.

'#aaa'
fill_extrusion_opacity float

Building opacity (0-1).

0.6
height_property str

Property name for building height in the vector tiles (default: 'render_height').

'render_height'
base_property str

Property name for building base height (default: 'render_min_height').

'render_min_height'
layer_id Optional[str]

Layer identifier. If None, uses '3d-buildings'.

None
**kwargs

Additional layer options.

{}

Examples:

>>> from anymap_ts import Map
>>> # Use a vector style with building data
>>> m = Map(
...     center=[-74.0060, 40.7128],
...     zoom=15,
...     pitch=60,
...     style="https://tiles.openfreemap.org/styles/liberty"
... )
>>> m.add_3d_buildings(
...     fill_extrusion_color="#4682B4",
...     fill_extrusion_opacity=0.8
... )
Source code in anymap_ts/maplibre.py
def add_3d_buildings(
    self,
    source: str = "openmaptiles",
    min_zoom: float = 14,
    fill_extrusion_color: str = "#aaa",
    fill_extrusion_opacity: float = 0.6,
    height_property: str = "render_height",
    base_property: str = "render_min_height",
    layer_id: Optional[str] = None,
    **kwargs,
) -> None:
    """Add 3D building extrusions from vector tiles.

    Creates 3D building visualizations using fill-extrusion layers.
    Works best with vector tile styles that include building data.

    Note:
        This feature requires a map style with vector tile building data.
        Recommended styles:
        - MapTiler styles (requires API key)
        - OpenFreeMap: "https://tiles.openfreemap.org/styles/liberty"
        - Protomaps styles

        CartoDB raster styles (Positron, DarkMatter) do NOT have building
        data. For those, the method will attempt to add OpenFreeMap tiles
        as a source, but results may vary.

    Args:
        source: Building source identifier. Usually auto-detected from
            the map style.
        min_zoom: Minimum zoom level to show buildings (default: 14).
        fill_extrusion_color: Building color as hex string.
        fill_extrusion_opacity: Building opacity (0-1).
        height_property: Property name for building height in the
            vector tiles (default: 'render_height').
        base_property: Property name for building base height
            (default: 'render_min_height').
        layer_id: Layer identifier. If None, uses '3d-buildings'.
        **kwargs: Additional layer options.

    Example:
        >>> from anymap_ts import Map
        >>> # Use a vector style with building data
        >>> m = Map(
        ...     center=[-74.0060, 40.7128],
        ...     zoom=15,
        ...     pitch=60,
        ...     style="https://tiles.openfreemap.org/styles/liberty"
        ... )
        >>> m.add_3d_buildings(
        ...     fill_extrusion_color="#4682B4",
        ...     fill_extrusion_opacity=0.8
        ... )
    """
    layer_name = layer_id or "3d-buildings"

    self.call_js_method(
        "add3DBuildings",
        source=source,
        minZoom=min_zoom,
        fillExtrusionColor=fill_extrusion_color,
        fillExtrusionOpacity=fill_extrusion_opacity,
        heightProperty=height_property,
        baseProperty=base_property,
        layerId=layer_name,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_name: {
            "id": layer_name,
            "type": "fill-extrusion",
        },
    }
    self._add_to_layer_dict(layer_name, "Vector")

add_3d_terrain(self, source='terrarium', exaggeration=1.0, **kwargs)

Enable 3D terrain visualization.

MapLibre GL JS supports 3D terrain rendering using elevation data from various terrain tile sources.

Parameters:

Name Type Description Default
source str

Terrain source - 'terrarium' (AWS terrain tiles) or 'mapbox' (requires Mapbox token) or custom terrain URL.

'terrarium'
exaggeration float

Vertical exaggeration factor. Default 1.0.

1.0
**kwargs

Additional terrain options.

{}

Examples:

>>> from anymap_ts import Map
>>> m = Map(center=[-122.4, 37.8], zoom=12, pitch=60)
>>> m.add_3d_terrain(exaggeration=1.5)
Source code in anymap_ts/maplibre.py
def add_3d_terrain(
    self,
    source: str = "terrarium",
    exaggeration: float = 1.0,
    **kwargs,
) -> None:
    """Enable 3D terrain visualization.

    MapLibre GL JS supports 3D terrain rendering using elevation data
    from various terrain tile sources.

    Args:
        source: Terrain source - 'terrarium' (AWS terrain tiles) or
            'mapbox' (requires Mapbox token) or custom terrain URL.
        exaggeration: Vertical exaggeration factor. Default 1.0.
        **kwargs: Additional terrain options.

    Example:
        >>> from anymap_ts import Map
        >>> m = Map(center=[-122.4, 37.8], zoom=12, pitch=60)
        >>> m.add_3d_terrain(exaggeration=1.5)
    """
    # Define terrain sources
    terrain_sources = {
        "terrarium": {
            "url": "https://s3.amazonaws.com/elevation-tiles-prod/terrarium/{z}/{x}/{y}.png",
            "encoding": "terrarium",
        },
        "mapbox": {
            "url": "mapbox://mapbox.mapbox-terrain-dem-v1",
            "encoding": "mapbox",
        },
    }

    if source in terrain_sources:
        terrain_config = terrain_sources[source]
    else:
        # Assume it's a custom URL
        terrain_config = {"url": source, "encoding": "terrarium"}

    self.call_js_method(
        "addTerrain",
        source=terrain_config,
        exaggeration=exaggeration,
        **kwargs,
    )

add_arc_layer(self, data, name=None, get_source_position='source', get_target_position='target', get_source_color=None, get_target_color=None, get_width=1, get_height=1, great_circle=False, pickable=True, opacity=0.8, **kwargs)

Add an arc layer for origin-destination visualization using deck.gl.

Arc layers are ideal for visualizing connections between locations, such as flight routes, migration patterns, or network flows.

Parameters:

Name Type Description Default
data Any

Array of data objects with source/target coordinates. Each object should have source and target positions.

required
name Optional[str]

Layer ID. If None, auto-generated.

None
get_source_position Union[str, Any]

Accessor for source position [lng, lat]. Can be a string (property name) or a value.

'source'
get_target_position Union[str, Any]

Accessor for target position [lng, lat]. Can be a string (property name) or a value.

'target'
get_source_color Optional[List[int]]

Source end color as [r, g, b, a]. Default: [51, 136, 255, 255] (blue).

None
get_target_color Optional[List[int]]

Target end color as [r, g, b, a]. Default: [255, 136, 51, 255] (orange).

None
get_width Union[float, str]

Arc width in pixels. Can be a number or accessor.

1
get_height float

Arc height multiplier. Higher values create more curved arcs.

1
great_circle bool

Whether to draw arcs along great circles.

False
pickable bool

Whether layer responds to hover/click events.

True
opacity float

Layer opacity (0-1).

0.8
**kwargs

Additional ArcLayer props.

{}

Examples:

>>> from anymap_ts import MapLibreMap
>>> m = MapLibreMap()
>>> arcs = [
...     {"source": [-122.4, 37.8], "target": [-73.9, 40.7]},
...     {"source": [-122.4, 37.8], "target": [-0.1, 51.5]},
... ]
>>> m.add_arc_layer(arcs, name="flights")
Source code in anymap_ts/maplibre.py
def add_arc_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_source_position: Union[str, Any] = "source",
    get_target_position: Union[str, Any] = "target",
    get_source_color: Optional[List[int]] = None,
    get_target_color: Optional[List[int]] = None,
    get_width: Union[float, str] = 1,
    get_height: float = 1,
    great_circle: bool = False,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add an arc layer for origin-destination visualization using deck.gl.

    Arc layers are ideal for visualizing connections between locations,
    such as flight routes, migration patterns, or network flows.

    Args:
        data: Array of data objects with source/target coordinates.
            Each object should have source and target positions.
        name: Layer ID. If None, auto-generated.
        get_source_position: Accessor for source position [lng, lat].
            Can be a string (property name) or a value.
        get_target_position: Accessor for target position [lng, lat].
            Can be a string (property name) or a value.
        get_source_color: Source end color as [r, g, b, a].
            Default: [51, 136, 255, 255] (blue).
        get_target_color: Target end color as [r, g, b, a].
            Default: [255, 136, 51, 255] (orange).
        get_width: Arc width in pixels. Can be a number or accessor.
        get_height: Arc height multiplier. Higher values create more curved arcs.
        great_circle: Whether to draw arcs along great circles.
        pickable: Whether layer responds to hover/click events.
        opacity: Layer opacity (0-1).
        **kwargs: Additional ArcLayer props.

    Example:
        >>> from anymap_ts import MapLibreMap
        >>> m = MapLibreMap()
        >>> arcs = [
        ...     {"source": [-122.4, 37.8], "target": [-73.9, 40.7]},
        ...     {"source": [-122.4, 37.8], "target": [-0.1, 51.5]},
        ... ]
        >>> m.add_arc_layer(arcs, name="flights")
    """
    layer_id = name or f"arc-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addArcLayer",
        id=layer_id,
        data=processed_data,
        getSourcePosition=get_source_position,
        getTargetPosition=get_target_position,
        getSourceColor=get_source_color or [51, 136, 255, 255],
        getTargetColor=get_target_color or [255, 136, 51, 255],
        getWidth=get_width,
        getHeight=get_height,
        greatCircle=great_circle,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "arc",
        },
    }
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_basemap(self, basemap='OpenStreetMap', attribution=None, **kwargs)

Add a basemap layer.

Parameters:

Name Type Description Default
basemap str

Name of basemap provider (e.g., "OpenStreetMap", "CartoDB.Positron")

'OpenStreetMap'
attribution Optional[str]

Custom attribution text

None
**kwargs

Additional options

{}
Source code in anymap_ts/maplibre.py
def add_basemap(
    self,
    basemap: str = "OpenStreetMap",
    attribution: Optional[str] = None,
    **kwargs,
) -> None:
    """Add a basemap layer.

    Args:
        basemap: Name of basemap provider (e.g., "OpenStreetMap", "CartoDB.Positron")
        attribution: Custom attribution text
        **kwargs: Additional options
    """
    url, default_attribution = get_basemap_url(basemap)
    self.call_js_method(
        "addBasemap",
        url,
        attribution=attribution or default_attribution,
        name=basemap,
        **kwargs,
    )

    # Track in layer dict
    basemaps = self._layer_dict.get("Basemaps", [])
    if basemap not in basemaps:
        self._layer_dict = {
            **self._layer_dict,
            "Basemaps": basemaps + [basemap],
        }

add_bitmap_layer(self, image, bounds, name=None, opacity=1.0, visible=True, pickable=False, desaturate=0, transparent_color=None, tint_color=None, **kwargs)

Add a bitmap layer for image overlay with GPU rendering using deck.gl.

Parameters:

Name Type Description Default
image str

URL or data URI of the image.

required
bounds List[float]

Bounding box [west, south, east, north].

required
name Optional[str]

Layer ID. If None, auto-generated.

None
opacity float

Layer opacity (0-1).

1.0
visible bool

Whether layer is visible.

True
pickable bool

Whether layer responds to hover/click events.

False
desaturate float

Desaturation amount (0-1).

0
transparent_color Optional[List[int]]

Color to make transparent [r, g, b, a].

None
tint_color Optional[List[int]]

Color to tint the image [r, g, b].

None
**kwargs

Additional BitmapLayer props.

{}

Examples:

>>> from anymap_ts import MapLibreMap
>>> m = MapLibreMap()
>>> m.add_bitmap_layer(
...     "https://example.com/overlay.png",
...     bounds=[-122.5, 37.7, -122.3, 37.9],
... )
Source code in anymap_ts/maplibre.py
def add_bitmap_layer(
    self,
    image: str,
    bounds: List[float],
    name: Optional[str] = None,
    opacity: float = 1.0,
    visible: bool = True,
    pickable: bool = False,
    desaturate: float = 0,
    transparent_color: Optional[List[int]] = None,
    tint_color: Optional[List[int]] = None,
    **kwargs,
) -> None:
    """Add a bitmap layer for image overlay with GPU rendering using deck.gl.

    Args:
        image: URL or data URI of the image.
        bounds: Bounding box [west, south, east, north].
        name: Layer ID. If None, auto-generated.
        opacity: Layer opacity (0-1).
        visible: Whether layer is visible.
        pickable: Whether layer responds to hover/click events.
        desaturate: Desaturation amount (0-1).
        transparent_color: Color to make transparent [r, g, b, a].
        tint_color: Color to tint the image [r, g, b].
        **kwargs: Additional BitmapLayer props.

    Example:
        >>> from anymap_ts import MapLibreMap
        >>> m = MapLibreMap()
        >>> m.add_bitmap_layer(
        ...     "https://example.com/overlay.png",
        ...     bounds=[-122.5, 37.7, -122.3, 37.9],
        ... )
    """
    layer_id = name or f"bitmap-{len(self._layers)}"

    self.call_js_method(
        "addBitmapLayer",
        id=layer_id,
        image=image,
        bounds=bounds,
        opacity=opacity,
        visible=visible,
        pickable=pickable,
        desaturate=desaturate,
        transparentColor=transparent_color or [0, 0, 0, 0],
        tintColor=tint_color or [255, 255, 255],
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {"id": layer_id, "type": "bitmap"},
    }
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_choropleth(self, data, column, cmap='viridis', classification='quantile', k=5, breaks=None, fill_opacity=0.7, line_color='#000000', line_width=1, legend=True, legend_title=None, hover=True, layer_id=None, fit_bounds=True, **kwargs)

Add a choropleth (thematic) map layer with automatic classification.

Choropleth maps use color gradients to visualize data values across geographic areas. This method automatically classifies data and applies appropriate colors.

Parameters:

Name Type Description Default
data Any

Polygon data - GeoJSON, GeoDataFrame, file path, or URL.

required
column str

Property name to visualize (must be numeric).

required
cmap str

Colormap name. Any matplotlib colormap is supported when matplotlib is installed. Common options include: - Sequential: 'viridis', 'plasma', 'inferno', 'magma', 'cividis', 'Blues', 'Greens', 'Reds', 'Oranges', 'Purples', 'Greys' - Diverging: 'RdBu', 'RdYlGn', 'RdYlBu', 'Spectral', 'coolwarm' - Qualitative: 'Set1', 'Set2', 'Set3', 'Paired', 'tab10', 'tab20' See: https://matplotlib.org/stable/gallery/color/colormap_reference.html

'viridis'
classification str

Classification method: - 'quantile': Equal number of features per class - 'equal_interval': Equal value ranges - 'natural_breaks': Jenks natural breaks (requires jenkspy) - 'manual': Use custom breaks

'quantile'
k int

Number of classes (ignored if classification='manual').

5
breaks Optional[List[float]]

Custom break values for 'manual' classification. Must have k+1 values defining class boundaries.

None
fill_opacity float

Polygon fill opacity (0-1).

0.7
line_color str

Polygon outline color.

'#000000'
line_width float

Polygon outline width.

1
legend bool

Whether to add a legend.

True
legend_title Optional[str]

Legend title. Defaults to column name.

None
hover bool

Whether to enable hover highlight effect.

True
layer_id Optional[str]

Layer identifier. If None, auto-generated.

None
fit_bounds bool

Whether to fit map to data bounds.

True
**kwargs

Additional layer options.

{}

Examples:

>>> from anymap_ts import Map
>>> m = Map()
>>> m.add_choropleth(
...     "us_states.geojson",
...     column="population",
...     cmap="YlOrRd",
...     classification="quantile",
...     k=5,
...     legend_title="Population"
... )
Source code in anymap_ts/maplibre.py
def add_choropleth(
    self,
    data: Any,
    column: str,
    cmap: str = "viridis",
    classification: str = "quantile",
    k: int = 5,
    breaks: Optional[List[float]] = None,
    fill_opacity: float = 0.7,
    line_color: str = "#000000",
    line_width: float = 1,
    legend: bool = True,
    legend_title: Optional[str] = None,
    hover: bool = True,
    layer_id: Optional[str] = None,
    fit_bounds: bool = True,
    **kwargs,
) -> None:
    """Add a choropleth (thematic) map layer with automatic classification.

    Choropleth maps use color gradients to visualize data values across
    geographic areas. This method automatically classifies data and applies
    appropriate colors.

    Args:
        data: Polygon data - GeoJSON, GeoDataFrame, file path, or URL.
        column: Property name to visualize (must be numeric).
        cmap: Colormap name. Any matplotlib colormap is supported when
            matplotlib is installed. Common options include:
            - Sequential: 'viridis', 'plasma', 'inferno', 'magma', 'cividis',
              'Blues', 'Greens', 'Reds', 'Oranges', 'Purples', 'Greys'
            - Diverging: 'RdBu', 'RdYlGn', 'RdYlBu', 'Spectral', 'coolwarm'
            - Qualitative: 'Set1', 'Set2', 'Set3', 'Paired', 'tab10', 'tab20'
            See: https://matplotlib.org/stable/gallery/color/colormap_reference.html
        classification: Classification method:
            - 'quantile': Equal number of features per class
            - 'equal_interval': Equal value ranges
            - 'natural_breaks': Jenks natural breaks (requires jenkspy)
            - 'manual': Use custom breaks
        k: Number of classes (ignored if classification='manual').
        breaks: Custom break values for 'manual' classification.
            Must have k+1 values defining class boundaries.
        fill_opacity: Polygon fill opacity (0-1).
        line_color: Polygon outline color.
        line_width: Polygon outline width.
        legend: Whether to add a legend.
        legend_title: Legend title. Defaults to column name.
        hover: Whether to enable hover highlight effect.
        layer_id: Layer identifier. If None, auto-generated.
        fit_bounds: Whether to fit map to data bounds.
        **kwargs: Additional layer options.

    Example:
        >>> from anymap_ts import Map
        >>> m = Map()
        >>> m.add_choropleth(
        ...     "us_states.geojson",
        ...     column="population",
        ...     cmap="YlOrRd",
        ...     classification="quantile",
        ...     k=5,
        ...     legend_title="Population"
        ... )
    """
    from .utils import (
        get_choropleth_colors,
        compute_breaks,
        build_step_expression,
    )

    layer_name = layer_id or f"choropleth-{len(self._layers)}"

    # Convert data to GeoJSON
    geojson = to_geojson(data)

    # Handle URL data - fetch GeoJSON
    if geojson.get("type") == "url":
        url = geojson["url"]
        geojson = fetch_geojson(url)

    # Extract values for classification
    features = geojson.get("features", [])
    values = []
    for feature in features:
        props = feature.get("properties", {})
        val = props.get(column)
        if val is not None:
            try:
                values.append(float(val))
            except (TypeError, ValueError):
                pass

    if not values:
        raise ValueError(f"No valid numeric values found for column '{column}'")

    # Compute breaks
    computed_breaks = compute_breaks(values, classification, k, breaks)

    # Get colors
    colors = get_choropleth_colors(cmap, k)

    # Build step expression for MapLibre
    step_expr = build_step_expression(column, computed_breaks, colors)

    # Get bounds
    bounds = get_bounds(geojson) if fit_bounds else None

    self.call_js_method(
        "addChoropleth",
        data=geojson,
        name=layer_name,
        column=column,
        stepExpression=step_expr,
        fillOpacity=fill_opacity,
        lineColor=line_color,
        lineWidth=line_width,
        hover=hover,
        fitBounds=fit_bounds,
        bounds=bounds,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_name: {
            "id": layer_name,
            "type": "choropleth",
            "source": f"{layer_name}-source",
            "column": column,
        },
    }
    self._add_to_layer_dict(layer_name, "Vector")

    # Add legend
    if legend:
        title = legend_title or column
        # Create labels from breaks
        labels = []
        for i in range(len(computed_breaks) - 1):
            low = computed_breaks[i]
            high = computed_breaks[i + 1]
            if i == len(computed_breaks) - 2:
                labels.append(f"{low:.1f} - {high:.1f}")
            else:
                labels.append(f"{low:.1f} - {high:.1f}")

        self.add_legend(
            title=title,
            labels=labels,
            colors=colors,
            position="bottom-right",
        )

add_cluster_layer(self, data, cluster_radius=50, cluster_max_zoom=14, cluster_colors=None, cluster_steps=None, cluster_min_radius=15, cluster_max_radius=30, unclustered_color='#11b4da', unclustered_radius=8, show_cluster_count=True, name=None, zoom_on_click=True, fit_bounds=True, **kwargs)

Add a clustered point layer with automatic grouping.

Creates a point layer that automatically clusters nearby points at lower zoom levels. Clicking on clusters zooms in to expand them.

Parameters:

Name Type Description Default
data Any

Point data - GeoJSON, GeoDataFrame, file path, or URL.

required
cluster_radius int

Radius of each cluster when grouping points (pixels).

50
cluster_max_zoom int

Max zoom level to cluster points (above this, all points are shown individually).

14
cluster_colors Optional[List[str]]

List of colors for cluster circles by size. Default: ["#51bbd6", "#f1f075", "#f28cb1"].

None
cluster_steps Optional[List[int]]

Point count thresholds for color changes. Default: [100, 750]. Must have len(cluster_colors) - 1 values.

None
cluster_min_radius int

Minimum cluster circle radius in pixels.

15
cluster_max_radius int

Maximum cluster circle radius in pixels.

30
unclustered_color str

Color for individual (unclustered) points.

'#11b4da'
unclustered_radius int

Radius for individual points in pixels.

8
show_cluster_count bool

Whether to show point count in clusters.

True
name Optional[str]

Layer identifier. If None, auto-generated.

None
zoom_on_click bool

Whether clicking clusters zooms in to expand them.

True
fit_bounds bool

Whether to fit map to data bounds.

True
**kwargs

Additional options.

{}

Returns:

Type Description
str

The layer identifier.

Examples:

>>> from anymap_ts import Map
>>> m = Map()
>>> m.add_cluster_layer(
...     "earthquakes.geojson",
...     cluster_radius=80,
...     cluster_colors=["#00ff00", "#ffff00", "#ff0000"],
...     cluster_steps=[50, 500],
... )
Source code in anymap_ts/maplibre.py
def add_cluster_layer(
    self,
    data: Any,
    cluster_radius: int = 50,
    cluster_max_zoom: int = 14,
    cluster_colors: Optional[List[str]] = None,
    cluster_steps: Optional[List[int]] = None,
    cluster_min_radius: int = 15,
    cluster_max_radius: int = 30,
    unclustered_color: str = "#11b4da",
    unclustered_radius: int = 8,
    show_cluster_count: bool = True,
    name: Optional[str] = None,
    zoom_on_click: bool = True,
    fit_bounds: bool = True,
    **kwargs,
) -> str:
    """Add a clustered point layer with automatic grouping.

    Creates a point layer that automatically clusters nearby points at
    lower zoom levels. Clicking on clusters zooms in to expand them.

    Args:
        data: Point data - GeoJSON, GeoDataFrame, file path, or URL.
        cluster_radius: Radius of each cluster when grouping points (pixels).
        cluster_max_zoom: Max zoom level to cluster points (above this, all
            points are shown individually).
        cluster_colors: List of colors for cluster circles by size.
            Default: ["#51bbd6", "#f1f075", "#f28cb1"].
        cluster_steps: Point count thresholds for color changes.
            Default: [100, 750]. Must have len(cluster_colors) - 1 values.
        cluster_min_radius: Minimum cluster circle radius in pixels.
        cluster_max_radius: Maximum cluster circle radius in pixels.
        unclustered_color: Color for individual (unclustered) points.
        unclustered_radius: Radius for individual points in pixels.
        show_cluster_count: Whether to show point count in clusters.
        name: Layer identifier. If None, auto-generated.
        zoom_on_click: Whether clicking clusters zooms in to expand them.
        fit_bounds: Whether to fit map to data bounds.
        **kwargs: Additional options.

    Returns:
        The layer identifier.

    Example:
        >>> from anymap_ts import Map
        >>> m = Map()
        >>> m.add_cluster_layer(
        ...     "earthquakes.geojson",
        ...     cluster_radius=80,
        ...     cluster_colors=["#00ff00", "#ffff00", "#ff0000"],
        ...     cluster_steps=[50, 500],
        ... )
    """
    layer_id = name or f"cluster-{len(self._layers)}"

    # Default colors and steps
    if cluster_colors is None:
        cluster_colors = ["#51bbd6", "#f1f075", "#f28cb1"]
    if cluster_steps is None:
        cluster_steps = [100, 750]

    # Validate steps vs colors
    if len(cluster_steps) != len(cluster_colors) - 1:
        raise ValueError(
            f"cluster_steps must have {len(cluster_colors) - 1} values "
            f"(one less than cluster_colors), got {len(cluster_steps)}"
        )

    # Convert data to GeoJSON
    geojson = to_geojson(data)

    # Handle URL data - fetch GeoJSON
    if geojson.get("type") == "url":
        url = geojson["url"]
        geojson = fetch_geojson(url)

    # Get bounds
    bounds = get_bounds(geojson) if fit_bounds else None

    self.call_js_method(
        "addClusterLayer",
        data=geojson,
        name=layer_id,
        clusterRadius=cluster_radius,
        clusterMaxZoom=cluster_max_zoom,
        clusterColors=cluster_colors,
        clusterSteps=cluster_steps,
        clusterMinRadius=cluster_min_radius,
        clusterMaxRadius=cluster_max_radius,
        unclusteredColor=unclustered_color,
        unclusteredRadius=unclustered_radius,
        showClusterCount=show_cluster_count,
        zoomOnClick=zoom_on_click,
        fitBounds=fit_bounds,
        bounds=bounds,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "cluster",
            "source": f"{layer_id}-source",
        },
    }
    self._add_to_layer_dict(layer_id, "Vector")
    return layer_id

add_cog_control(self, position='top-right', collapsed=True, default_url=None, load_default_url=False, default_opacity=1.0, default_colormap='viridis', default_bands='1', default_rescale_min=0, default_rescale_max=255, **kwargs)

Add a COG layer control for loading Cloud Optimized GeoTIFFs via UI.

This provides an interactive panel for users to enter COG URLs and configure visualization parameters like colormap and rescaling.

Parameters:

Name Type Description Default
position str

Control position ('top-left', 'top-right', 'bottom-left', 'bottom-right').

'top-right'
collapsed bool

Whether the panel starts collapsed.

True
default_url Optional[str]

Default COG URL to pre-fill.

None
load_default_url bool

Whether to auto-load the default URL.

False
default_opacity float

Default layer opacity (0-1).

1.0
default_colormap str

Default colormap name.

'viridis'
default_bands str

Default bands (e.g., '1' or '1,2,3').

'1'
default_rescale_min float

Default minimum value for rescaling.

0
default_rescale_max float

Default maximum value for rescaling.

255
**kwargs

Additional control options.

{}

Examples:

>>> from anymap_ts import MapLibreMap
>>> m = MapLibreMap()
>>> m.add_cog_control(
...     default_url="https://example.com/cog.tif",
...     default_colormap="terrain"
... )
Source code in anymap_ts/maplibre.py
def add_cog_control(
    self,
    position: str = "top-right",
    collapsed: bool = True,
    default_url: Optional[str] = None,
    load_default_url: bool = False,
    default_opacity: float = 1.0,
    default_colormap: str = "viridis",
    default_bands: str = "1",
    default_rescale_min: float = 0,
    default_rescale_max: float = 255,
    **kwargs,
) -> None:
    """Add a COG layer control for loading Cloud Optimized GeoTIFFs via UI.

    This provides an interactive panel for users to enter COG URLs
    and configure visualization parameters like colormap and rescaling.

    Args:
        position: Control position ('top-left', 'top-right', 'bottom-left', 'bottom-right').
        collapsed: Whether the panel starts collapsed.
        default_url: Default COG URL to pre-fill.
        load_default_url: Whether to auto-load the default URL.
        default_opacity: Default layer opacity (0-1).
        default_colormap: Default colormap name.
        default_bands: Default bands (e.g., '1' or '1,2,3').
        default_rescale_min: Default minimum value for rescaling.
        default_rescale_max: Default maximum value for rescaling.
        **kwargs: Additional control options.

    Example:
        >>> from anymap_ts import MapLibreMap
        >>> m = MapLibreMap()
        >>> m.add_cog_control(
        ...     default_url="https://example.com/cog.tif",
        ...     default_colormap="terrain"
        ... )
    """
    self.call_js_method(
        "addCogControl",
        position=position,
        collapsed=collapsed,
        defaultUrl=default_url or "",
        loadDefaultUrl=load_default_url,
        defaultOpacity=default_opacity,
        defaultColormap=default_colormap,
        defaultBands=default_bands,
        defaultRescaleMin=default_rescale_min,
        defaultRescaleMax=default_rescale_max,
        **kwargs,
    )
    self._controls = {
        **self._controls,
        "cog-control": {"position": position, "collapsed": collapsed},
    }

add_cog_layer(self, url, name=None, opacity=1.0, visible=True, debug=False, debug_opacity=0.25, max_error=0.125, fit_bounds=True, before_id=None, **kwargs)

Add a Cloud Optimized GeoTIFF (COG) layer using @developmentseed/deck.gl-geotiff.

This method renders COG files directly in the browser using GPU-accelerated deck.gl-geotiff rendering with automatic reprojection support.

Parameters:

Name Type Description Default
url str

URL to the Cloud Optimized GeoTIFF file.

required
name Optional[str]

Layer ID. If None, auto-generated.

None
opacity float

Layer opacity (0-1).

1.0
visible bool

Whether layer is visible.

True
debug bool

Show reprojection mesh for debugging.

False
debug_opacity float

Opacity of debug mesh (0-1).

0.25
max_error float

Maximum reprojection error in pixels. Lower values create denser mesh for better accuracy.

0.125
fit_bounds bool

Whether to fit map to COG bounds after loading.

True
before_id Optional[str]

ID of layer to insert before.

None
**kwargs

Additional COGLayer props.

{}

Examples:

>>> from anymap_ts import Map
>>> m = Map()
>>> m.add_cog_layer(
...     "https://example.com/landcover.tif",
...     name="landcover",
...     opacity=0.8
... )
Source code in anymap_ts/maplibre.py
def add_cog_layer(
    self,
    url: str,
    name: Optional[str] = None,
    opacity: float = 1.0,
    visible: bool = True,
    debug: bool = False,
    debug_opacity: float = 0.25,
    max_error: float = 0.125,
    fit_bounds: bool = True,
    before_id: Optional[str] = None,
    **kwargs,
) -> None:
    """Add a Cloud Optimized GeoTIFF (COG) layer using @developmentseed/deck.gl-geotiff.

    This method renders COG files directly in the browser using GPU-accelerated
    deck.gl-geotiff rendering with automatic reprojection support.

    Args:
        url: URL to the Cloud Optimized GeoTIFF file.
        name: Layer ID. If None, auto-generated.
        opacity: Layer opacity (0-1).
        visible: Whether layer is visible.
        debug: Show reprojection mesh for debugging.
        debug_opacity: Opacity of debug mesh (0-1).
        max_error: Maximum reprojection error in pixels. Lower values
            create denser mesh for better accuracy.
        fit_bounds: Whether to fit map to COG bounds after loading.
        before_id: ID of layer to insert before.
        **kwargs: Additional COGLayer props.

    Example:
        >>> from anymap_ts import Map
        >>> m = Map()
        >>> m.add_cog_layer(
        ...     "https://example.com/landcover.tif",
        ...     name="landcover",
        ...     opacity=0.8
        ... )
    """
    layer_id = name or f"cog-{len(self._layers)}"

    self.call_js_method(
        "addCOGLayer",
        id=layer_id,
        geotiff=url,
        opacity=opacity,
        visible=visible,
        debug=debug,
        debugOpacity=debug_opacity,
        maxError=max_error,
        fitBounds=fit_bounds,
        beforeId=before_id,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "cog",
            "url": url,
        },
    }
    self._add_to_layer_dict(layer_id, "Raster")

add_colorbar(self, colormap='viridis', vmin=0, vmax=1, label='', units='', orientation='horizontal', position='bottom-right', bar_thickness=None, bar_length=None, ticks=None, opacity=None, colorbar_id=None, **kwargs)

Add a continuous gradient colorbar to the map.

Displays a color gradient legend with customizable colormaps, tick marks, labels, and positioning using maplibre-gl-components.

Parameters:

Name Type Description Default
colormap str

Colormap name (e.g., 'viridis', 'plasma', 'inferno', 'magma', 'cividis', 'coolwarm', 'jet', 'terrain', etc.).

'viridis'
vmin float

Minimum value for the colorbar scale.

0
vmax float

Maximum value for the colorbar scale.

1
label str

Title/label displayed above or beside the colorbar.

''
units str

Unit string displayed after values (e.g., '°C', 'm').

''
orientation str

Orientation of the colorbar ('horizontal' or 'vertical').

'horizontal'
position str

Control position ('top-left', 'top-right', 'bottom-left', 'bottom-right').

'bottom-right'
bar_thickness Optional[int]

Width/height of the gradient bar in pixels.

None
bar_length Optional[int]

Length of the colorbar in pixels.

None
ticks Optional[Dict]

Tick configuration dict (e.g., {'count': 5, 'precision': 2}).

None
opacity Optional[float]

Opacity of the colorbar container (0-1).

None
colorbar_id Optional[str]

Unique identifier. If None, auto-generated.

None
**kwargs

Additional Colorbar options.

{}

Examples:

>>> m = Map()
>>> m.add_cog_layer("https://example.com/dem.tif")
>>> m.add_colorbar(
...     colormap="terrain",
...     vmin=0,
...     vmax=4000,
...     label="Elevation",
...     units="m",
... )
Source code in anymap_ts/maplibre.py
def add_colorbar(
    self,
    colormap: str = "viridis",
    vmin: float = 0,
    vmax: float = 1,
    label: str = "",
    units: str = "",
    orientation: str = "horizontal",
    position: str = "bottom-right",
    bar_thickness: Optional[int] = None,
    bar_length: Optional[int] = None,
    ticks: Optional[Dict] = None,
    opacity: Optional[float] = None,
    colorbar_id: Optional[str] = None,
    **kwargs,
) -> None:
    """Add a continuous gradient colorbar to the map.

    Displays a color gradient legend with customizable colormaps,
    tick marks, labels, and positioning using maplibre-gl-components.

    Args:
        colormap: Colormap name (e.g., 'viridis', 'plasma', 'inferno',
            'magma', 'cividis', 'coolwarm', 'jet', 'terrain', etc.).
        vmin: Minimum value for the colorbar scale.
        vmax: Maximum value for the colorbar scale.
        label: Title/label displayed above or beside the colorbar.
        units: Unit string displayed after values (e.g., '°C', 'm').
        orientation: Orientation of the colorbar ('horizontal' or 'vertical').
        position: Control position ('top-left', 'top-right',
            'bottom-left', 'bottom-right').
        bar_thickness: Width/height of the gradient bar in pixels.
        bar_length: Length of the colorbar in pixels.
        ticks: Tick configuration dict (e.g., {'count': 5, 'precision': 2}).
        opacity: Opacity of the colorbar container (0-1).
        colorbar_id: Unique identifier. If None, auto-generated.
        **kwargs: Additional Colorbar options.

    Example:
        >>> m = Map()
        >>> m.add_cog_layer("https://example.com/dem.tif")
        >>> m.add_colorbar(
        ...     colormap="terrain",
        ...     vmin=0,
        ...     vmax=4000,
        ...     label="Elevation",
        ...     units="m",
        ... )
    """
    self._validate_position(position)

    cbar_id = (
        colorbar_id
        or f"colorbar-{len([k for k in self._controls.keys() if k.startswith('colorbar')])}"
    )

    js_kwargs: Dict[str, Any] = {
        "colormap": colormap,
        "vmin": vmin,
        "vmax": vmax,
        "label": label,
        "units": units,
        "orientation": orientation,
        "position": position,
        "colorbarId": cbar_id,
        **kwargs,
    }
    if bar_thickness is not None:
        js_kwargs["barThickness"] = bar_thickness
    if bar_length is not None:
        js_kwargs["barLength"] = bar_length
    if ticks is not None:
        js_kwargs["ticks"] = ticks
    if opacity is not None:
        js_kwargs["opacity"] = opacity

    self.call_js_method("addColorbar", **js_kwargs)

    self._controls = {
        **self._controls,
        cbar_id: {
            "type": "colorbar",
            "colormap": colormap,
            "vmin": vmin,
            "vmax": vmax,
            "label": label,
            "units": units,
            "orientation": orientation,
            "position": position,
        },
    }

add_column_layer(self, data, name=None, get_position='coordinates', get_fill_color=None, get_line_color=None, get_elevation=1000, radius=1000, disk_resolution=20, elevation_scale=1, coverage=1, extruded=True, filled=True, stroked=False, wireframe=False, pickable=True, opacity=0.8, **kwargs)

Add a column layer for 3D bar chart visualization using deck.gl.

Column layers render cylindrical columns at specified positions, ideal for 3D bar charts on a map.

Parameters:

Name Type Description Default
data Any

Array of data objects with position coordinates.

required
name Optional[str]

Layer ID. If None, auto-generated.

None
get_position Union[str, Any]

Accessor for column position [lng, lat].

'coordinates'
get_fill_color Optional[Union[List[int], str]]

Accessor for fill color [r, g, b, a].

None
get_line_color Optional[Union[List[int], str]]

Accessor for stroke color [r, g, b, a].

None
get_elevation Union[float, str]

Accessor for column height.

1000
radius float

Column radius in meters.

1000
disk_resolution int

Number of sides for column polygon.

20
elevation_scale float

Elevation multiplier.

1
coverage float

Column coverage (0-1).

1
extruded bool

Whether to extrude columns.

True
filled bool

Whether to fill columns.

True
stroked bool

Whether to stroke columns.

False
wireframe bool

Whether to render as wireframe.

False
pickable bool

Whether layer responds to hover/click events.

True
opacity float

Layer opacity (0-1).

0.8
**kwargs

Additional ColumnLayer props.

{}

Examples:

>>> from anymap_ts import MapLibreMap
>>> m = MapLibreMap(pitch=45)
>>> data = [
...     {"coordinates": [-122.4, 37.8], "value": 500},
...     {"coordinates": [-122.5, 37.7], "value": 1000},
... ]
>>> m.add_column_layer(data, get_elevation="value", radius=500)
Source code in anymap_ts/maplibre.py
def add_column_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_position: Union[str, Any] = "coordinates",
    get_fill_color: Optional[Union[List[int], str]] = None,
    get_line_color: Optional[Union[List[int], str]] = None,
    get_elevation: Union[float, str] = 1000,
    radius: float = 1000,
    disk_resolution: int = 20,
    elevation_scale: float = 1,
    coverage: float = 1,
    extruded: bool = True,
    filled: bool = True,
    stroked: bool = False,
    wireframe: bool = False,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add a column layer for 3D bar chart visualization using deck.gl.

    Column layers render cylindrical columns at specified positions,
    ideal for 3D bar charts on a map.

    Args:
        data: Array of data objects with position coordinates.
        name: Layer ID. If None, auto-generated.
        get_position: Accessor for column position [lng, lat].
        get_fill_color: Accessor for fill color [r, g, b, a].
        get_line_color: Accessor for stroke color [r, g, b, a].
        get_elevation: Accessor for column height.
        radius: Column radius in meters.
        disk_resolution: Number of sides for column polygon.
        elevation_scale: Elevation multiplier.
        coverage: Column coverage (0-1).
        extruded: Whether to extrude columns.
        filled: Whether to fill columns.
        stroked: Whether to stroke columns.
        wireframe: Whether to render as wireframe.
        pickable: Whether layer responds to hover/click events.
        opacity: Layer opacity (0-1).
        **kwargs: Additional ColumnLayer props.

    Example:
        >>> from anymap_ts import MapLibreMap
        >>> m = MapLibreMap(pitch=45)
        >>> data = [
        ...     {"coordinates": [-122.4, 37.8], "value": 500},
        ...     {"coordinates": [-122.5, 37.7], "value": 1000},
        ... ]
        >>> m.add_column_layer(data, get_elevation="value", radius=500)
    """
    layer_id = name or f"column-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addColumnLayer",
        id=layer_id,
        data=processed_data,
        getPosition=get_position,
        getFillColor=get_fill_color or [255, 140, 0, 200],
        getLineColor=get_line_color or [0, 0, 0, 255],
        getElevation=get_elevation,
        radius=radius,
        diskResolution=disk_resolution,
        elevationScale=elevation_scale,
        coverage=coverage,
        extruded=extruded,
        filled=filled,
        stroked=stroked,
        wireframe=wireframe,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {"id": layer_id, "type": "column"},
    }
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_contour_layer(self, data, name=None, get_position='coordinates', get_weight=1, cell_size=200, contours=None, pickable=True, opacity=1, **kwargs)

Add a contour layer for isoline/isoband generation using deck.gl.

Contour layers aggregate point data and generate isolines or isobands, ideal for density visualization and topographic-style maps.

Parameters:

Name Type Description Default
data Any

Array of data objects with position coordinates.

required
name Optional[str]

Layer ID. If None, auto-generated.

None
get_position Union[str, Any]

Accessor for point position [lng, lat].

'coordinates'
get_weight Union[float, str]

Accessor for point weight value.

1
cell_size float

Grid cell size for aggregation in meters.

200
contours Optional[List[Dict]]

Contour definitions [{threshold, color, strokeWidth}, ...].

None
pickable bool

Whether layer responds to hover/click events.

True
opacity float

Layer opacity (0-1).

1
**kwargs

Additional ContourLayer props.

{}

Examples:

>>> from anymap_ts import MapLibreMap
>>> m = MapLibreMap()
>>> points = [
...     {"coordinates": [-122.4, 37.8], "weight": 5},
...     {"coordinates": [-122.41, 37.81], "weight": 10},
... ]
>>> m.add_contour_layer(points, contours=[
...     {"threshold": 1, "color": [255, 255, 178], "strokeWidth": 1},
...     {"threshold": 5, "color": [253, 141, 60], "strokeWidth": 2},
... ])
Source code in anymap_ts/maplibre.py
def add_contour_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_position: Union[str, Any] = "coordinates",
    get_weight: Union[float, str] = 1,
    cell_size: float = 200,
    contours: Optional[List[Dict]] = None,
    pickable: bool = True,
    opacity: float = 1,
    **kwargs,
) -> None:
    """Add a contour layer for isoline/isoband generation using deck.gl.

    Contour layers aggregate point data and generate isolines or isobands,
    ideal for density visualization and topographic-style maps.

    Args:
        data: Array of data objects with position coordinates.
        name: Layer ID. If None, auto-generated.
        get_position: Accessor for point position [lng, lat].
        get_weight: Accessor for point weight value.
        cell_size: Grid cell size for aggregation in meters.
        contours: Contour definitions [{threshold, color, strokeWidth}, ...].
        pickable: Whether layer responds to hover/click events.
        opacity: Layer opacity (0-1).
        **kwargs: Additional ContourLayer props.

    Example:
        >>> from anymap_ts import MapLibreMap
        >>> m = MapLibreMap()
        >>> points = [
        ...     {"coordinates": [-122.4, 37.8], "weight": 5},
        ...     {"coordinates": [-122.41, 37.81], "weight": 10},
        ... ]
        >>> m.add_contour_layer(points, contours=[
        ...     {"threshold": 1, "color": [255, 255, 178], "strokeWidth": 1},
        ...     {"threshold": 5, "color": [253, 141, 60], "strokeWidth": 2},
        ... ])
    """
    layer_id = name or f"contour-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    default_contours = [
        {"threshold": 1, "color": [255, 255, 255], "strokeWidth": 1},
        {"threshold": 5, "color": [51, 136, 255], "strokeWidth": 2},
        {"threshold": 10, "color": [0, 0, 255], "strokeWidth": 3},
    ]

    self.call_js_method(
        "addContourLayer",
        id=layer_id,
        data=processed_data,
        getPosition=get_position,
        getWeight=get_weight,
        cellSize=cell_size,
        contours=contours or default_contours,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "contour",
        },
    }
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_control(self, control_type, position='top-right', **kwargs)

Add a map control.

Parameters:

Name Type Description Default
control_type str

Type of control ('navigation', 'scale', 'fullscreen', etc.)

required
position str

Control position

'top-right'
**kwargs

Control-specific options

{}
Source code in anymap_ts/maplibre.py
def add_control(
    self,
    control_type: str,
    position: str = "top-right",
    **kwargs,
) -> None:
    """Add a map control.

    Args:
        control_type: Type of control ('navigation', 'scale', 'fullscreen', etc.)
        position: Control position
        **kwargs: Control-specific options
    """
    self.call_js_method("addControl", control_type, position=position, **kwargs)
    self._controls = {
        **self._controls,
        control_type: {"type": control_type, "position": position, **kwargs},
    }

add_control_grid(self, position='top-right', default_controls=None, exclude=None, rows=None, columns=None, collapsed=True, collapsible=True, title='', show_row_column_controls=True, gap=2, basemap_style_url=None, exclude_layers=None, **kwargs)

Add a ControlGrid with all default tools or a custom subset.

The ControlGrid provides a collapsible toolbar with up to 26 built-in controls (search, basemap, terrain, measure, draw, etc.) in a configurable grid layout.

Parameters:

Name Type Description Default
position str

Control position ('top-left', 'top-right', 'bottom-left', 'bottom-right').

'top-right'
default_controls Optional[List[str]]

Explicit list of control names to include. If None, all 26 default controls are used (minus any in exclude). Valid names: 'globe', 'fullscreen', 'north', 'terrain', 'search', 'viewState', 'inspect', 'vectorDataset', 'basemap', 'measure', 'geoEditor', 'bookmark', 'print', 'minimap', 'swipe', 'streetView', 'addVector', 'cogLayer', 'zarrLayer', 'pmtilesLayer', 'stacLayer', 'stacSearch', 'planetaryComputer', 'gaussianSplat', 'lidar', 'usgsLidar'.

None
exclude Optional[List[str]]

Controls to remove from the default set. Ignored when default_controls is provided.

None
rows Optional[int]

Number of grid rows (auto-calculated if None).

None
columns Optional[int]

Number of grid columns (auto-calculated if None).

None
collapsed bool

Whether the grid starts collapsed. Default True.

True
collapsible bool

Whether the grid can be collapsed. Default True.

True
title str

Optional header title for the grid.

''
show_row_column_controls bool

Show row/column input fields. Default True.

True
gap int

Gap between grid cells in pixels. Default 2.

2
basemap_style_url Optional[str]

Basemap style URL for SwipeControl layer grouping. If None, the current map style is used automatically.

None
exclude_layers Optional[List[str]]

Layer ID patterns to exclude from SwipeControl (e.g., 'measure-', 'gl-draw-'). If None, sensible defaults are applied.

None
**kwargs

Additional ControlGrid options.

{}

Examples:

>>> from anymap_ts import MapLibreMap
>>> m = MapLibreMap()
>>> m.add_control_grid()  # All 26 controls
>>> # Or with customization:
>>> m.add_control_grid(
...     exclude=["minimap", "streetView"],
...     collapsed=True,
... )
Source code in anymap_ts/maplibre.py
def add_control_grid(
    self,
    position: str = "top-right",
    default_controls: Optional[List[str]] = None,
    exclude: Optional[List[str]] = None,
    rows: Optional[int] = None,
    columns: Optional[int] = None,
    collapsed: bool = True,
    collapsible: bool = True,
    title: str = "",
    show_row_column_controls: bool = True,
    gap: int = 2,
    basemap_style_url: Optional[str] = None,
    exclude_layers: Optional[List[str]] = None,
    **kwargs,
) -> None:
    """Add a ControlGrid with all default tools or a custom subset.

    The ControlGrid provides a collapsible toolbar with up to 26 built-in
    controls (search, basemap, terrain, measure, draw, etc.) in a
    configurable grid layout.

    Args:
        position: Control position ('top-left', 'top-right', 'bottom-left',
            'bottom-right').
        default_controls: Explicit list of control names to include. If None,
            all 26 default controls are used (minus any in ``exclude``).
            Valid names: 'globe', 'fullscreen', 'north', 'terrain', 'search',
            'viewState', 'inspect', 'vectorDataset', 'basemap', 'measure',
            'geoEditor', 'bookmark', 'print', 'minimap', 'swipe',
            'streetView', 'addVector', 'cogLayer', 'zarrLayer',
            'pmtilesLayer', 'stacLayer', 'stacSearch', 'planetaryComputer',
            'gaussianSplat', 'lidar', 'usgsLidar'.
        exclude: Controls to remove from the default set. Ignored when
            ``default_controls`` is provided.
        rows: Number of grid rows (auto-calculated if None).
        columns: Number of grid columns (auto-calculated if None).
        collapsed: Whether the grid starts collapsed. Default True.
        collapsible: Whether the grid can be collapsed. Default True.
        title: Optional header title for the grid.
        show_row_column_controls: Show row/column input fields. Default True.
        gap: Gap between grid cells in pixels. Default 2.
        basemap_style_url: Basemap style URL for SwipeControl layer grouping.
            If None, the current map style is used automatically.
        exclude_layers: Layer ID patterns to exclude from SwipeControl
            (e.g., 'measure-*', 'gl-draw-*'). If None, sensible defaults
            are applied.
        **kwargs: Additional ControlGrid options.

    Example:
        >>> from anymap_ts import MapLibreMap
        >>> m = MapLibreMap()
        >>> m.add_control_grid()  # All 26 controls
        >>> # Or with customization:
        >>> m.add_control_grid(
        ...     exclude=["minimap", "streetView"],
        ...     collapsed=True,
        ... )
    """
    js_kwargs: Dict[str, Any] = {
        "position": position,
        "collapsed": collapsed,
        "collapsible": collapsible,
        "showRowColumnControls": show_row_column_controls,
        "gap": gap,
        **kwargs,
    }
    if default_controls is not None:
        js_kwargs["defaultControls"] = default_controls
    if exclude is not None:
        js_kwargs["exclude"] = exclude
    if rows is not None:
        js_kwargs["rows"] = rows
    if columns is not None:
        js_kwargs["columns"] = columns
    if title:
        js_kwargs["title"] = title
    if basemap_style_url is not None:
        js_kwargs["basemapStyleUrl"] = basemap_style_url
    if exclude_layers is not None:
        js_kwargs["excludeLayers"] = exclude_layers

    self.call_js_method("addControlGrid", **js_kwargs)
    # Save full config for HTML export
    control_config = {
        "position": position,
        "collapsed": collapsed,
        "collapsible": collapsible,
    }
    if default_controls is not None:
        control_config["defaultControls"] = default_controls
    if exclude is not None:
        control_config["exclude"] = exclude
    if rows is not None:
        control_config["rows"] = rows
    if columns is not None:
        control_config["columns"] = columns
    self._controls = {
        **self._controls,
        "control-grid": control_config,
    }

add_coordinates_control(self, position='bottom-left', precision=4)

Add a coordinates display showing cursor lat/lng.

Parameters:

Name Type Description Default
position str

Control position ('top-left', 'top-right', 'bottom-left', 'bottom-right').

'bottom-left'
precision int

Number of decimal places for coordinates.

4

Examples:

>>> m = MapLibreMap()
>>> m.add_coordinates_control(position="bottom-left", precision=6)
Source code in anymap_ts/maplibre.py
def add_coordinates_control(
    self,
    position: str = "bottom-left",
    precision: int = 4,
) -> None:
    """Add a coordinates display showing cursor lat/lng.

    Args:
        position: Control position ('top-left', 'top-right',
            'bottom-left', 'bottom-right').
        precision: Number of decimal places for coordinates.

    Example:
        >>> m = MapLibreMap()
        >>> m.add_coordinates_control(position="bottom-left", precision=6)
    """
    self.call_js_method(
        "addCoordinatesControl",
        position=position,
        precision=precision,
    )

add_deck_heatmap_layer(self, data, name=None, get_position='coordinates', get_weight=1, radius_pixels=30, intensity=1, threshold=0.05, color_range=None, opacity=1, **kwargs)

Add a GPU-accelerated heatmap layer using deck.gl.

This is an alternative to the native MapLibre heatmap layer, using deck.gl's GPU-based rendering for better performance with large datasets.

Parameters:

Name Type Description Default
data Any

Array of data objects with position coordinates.

required
name Optional[str]

Layer ID. If None, auto-generated.

None
get_position Union[str, Any]

Accessor for point position [lng, lat].

'coordinates'
get_weight Union[float, str]

Accessor for point weight value.

1
radius_pixels float

Influence radius in pixels.

30
intensity float

Intensity multiplier.

1
threshold float

Minimum density threshold (0-1).

0.05
color_range Optional[List[List[int]]]

Color gradient [[r, g, b, a], ...].

None
opacity float

Layer opacity (0-1).

1
**kwargs

Additional HeatmapLayer props.

{}

Examples:

>>> from anymap_ts import MapLibreMap
>>> m = MapLibreMap()
>>> points = [
...     {"coordinates": [-122.4, 37.8], "weight": 5},
...     {"coordinates": [-122.5, 37.7], "weight": 10},
... ]
>>> m.add_deck_heatmap_layer(points, get_weight="weight")
Source code in anymap_ts/maplibre.py
def add_deck_heatmap_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_position: Union[str, Any] = "coordinates",
    get_weight: Union[float, str] = 1,
    radius_pixels: float = 30,
    intensity: float = 1,
    threshold: float = 0.05,
    color_range: Optional[List[List[int]]] = None,
    opacity: float = 1,
    **kwargs,
) -> None:
    """Add a GPU-accelerated heatmap layer using deck.gl.

    This is an alternative to the native MapLibre heatmap layer, using
    deck.gl's GPU-based rendering for better performance with large datasets.

    Args:
        data: Array of data objects with position coordinates.
        name: Layer ID. If None, auto-generated.
        get_position: Accessor for point position [lng, lat].
        get_weight: Accessor for point weight value.
        radius_pixels: Influence radius in pixels.
        intensity: Intensity multiplier.
        threshold: Minimum density threshold (0-1).
        color_range: Color gradient [[r, g, b, a], ...].
        opacity: Layer opacity (0-1).
        **kwargs: Additional HeatmapLayer props.

    Example:
        >>> from anymap_ts import MapLibreMap
        >>> m = MapLibreMap()
        >>> points = [
        ...     {"coordinates": [-122.4, 37.8], "weight": 5},
        ...     {"coordinates": [-122.5, 37.7], "weight": 10},
        ... ]
        >>> m.add_deck_heatmap_layer(points, get_weight="weight")
    """
    layer_id = name or f"deck-heatmap-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    default_color_range = [
        [255, 255, 178, 25],
        [254, 217, 118, 85],
        [254, 178, 76, 127],
        [253, 141, 60, 170],
        [240, 59, 32, 212],
        [189, 0, 38, 255],
    ]

    self.call_js_method(
        "addHeatmapLayer",
        id=layer_id,
        data=processed_data,
        getPosition=get_position,
        getWeight=get_weight,
        radiusPixels=radius_pixels,
        intensity=intensity,
        threshold=threshold,
        colorRange=color_range or default_color_range,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "deck-heatmap",
        },
    }
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_deckgl_layer(self, layer_type, data, name=None, **kwargs)

Add a generic deck.gl layer to the map.

This method provides a flexible way to add any supported deck.gl layer type using a single interface. For commonly used layers, prefer the specific methods (e.g., add_scatterplot_layer) for better IDE support.

Parameters:

Name Type Description Default
layer_type str

The deck.gl layer type (e.g., 'ScatterplotLayer', 'ArcLayer', 'HexagonLayer').

required
data Any

Array of data objects or GeoJSON.

required
name Optional[str]

Layer ID. If None, auto-generated from layer_type.

None
**kwargs

Layer-specific properties passed directly to deck.gl.

{}

Examples:

>>> from anymap_ts import MapLibreMap
>>> m = MapLibreMap()
>>> m.add_deckgl_layer(
...     "TripsLayer",
...     data=trips_data,
...     getPath="waypoints",
...     getTimestamps="timestamps",
...     trailLength=180,
... )
Source code in anymap_ts/maplibre.py
def add_deckgl_layer(
    self,
    layer_type: str,
    data: Any,
    name: Optional[str] = None,
    **kwargs,
) -> None:
    """Add a generic deck.gl layer to the map.

    This method provides a flexible way to add any supported deck.gl layer
    type using a single interface. For commonly used layers, prefer the
    specific methods (e.g., add_scatterplot_layer) for better IDE support.

    Args:
        layer_type: The deck.gl layer type (e.g., 'ScatterplotLayer',
            'ArcLayer', 'HexagonLayer').
        data: Array of data objects or GeoJSON.
        name: Layer ID. If None, auto-generated from layer_type.
        **kwargs: Layer-specific properties passed directly to deck.gl.

    Example:
        >>> from anymap_ts import MapLibreMap
        >>> m = MapLibreMap()
        >>> m.add_deckgl_layer(
        ...     "TripsLayer",
        ...     data=trips_data,
        ...     getPath="waypoints",
        ...     getTimestamps="timestamps",
        ...     trailLength=180,
        ... )
    """
    layer_type_clean = layer_type.replace("Layer", "")
    prefix = layer_type_clean.lower()
    layer_id = name or f"{prefix}-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addDeckGLLayer",
        layerType=layer_type,
        id=layer_id,
        data=processed_data,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": layer_type,
        },
    }
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_draw_control(self, position='top-right', draw_modes=None, edit_modes=None, collapsed=False, **kwargs)

Add a drawing control using maplibre-gl-geo-editor.

Parameters:

Name Type Description Default
position str

Control position

'top-right'
draw_modes Optional[List[str]]

Drawing modes to enable (e.g., ['polygon', 'line', 'marker'])

None
edit_modes Optional[List[str]]

Edit modes to enable (e.g., ['select', 'drag', 'delete'])

None
collapsed bool

Whether control starts collapsed

False
**kwargs

Additional geo-editor options

{}
Source code in anymap_ts/maplibre.py
def add_draw_control(
    self,
    position: str = "top-right",
    draw_modes: Optional[List[str]] = None,
    edit_modes: Optional[List[str]] = None,
    collapsed: bool = False,
    **kwargs,
) -> None:
    """Add a drawing control using maplibre-gl-geo-editor.

    Args:
        position: Control position
        draw_modes: Drawing modes to enable (e.g., ['polygon', 'line', 'marker'])
        edit_modes: Edit modes to enable (e.g., ['select', 'drag', 'delete'])
        collapsed: Whether control starts collapsed
        **kwargs: Additional geo-editor options
    """
    if draw_modes is None:
        draw_modes = ["polygon", "line", "rectangle", "circle", "marker"]
    if edit_modes is None:
        edit_modes = ["select", "drag", "change", "rotate", "delete"]

    self.call_js_method(
        "addDrawControl",
        position=position,
        drawModes=draw_modes,
        editModes=edit_modes,
        collapsed=collapsed,
        **kwargs,
    )
    self._controls = {
        **self._controls,
        "draw-control": {
            "position": position,
            "drawModes": draw_modes,
            "editModes": edit_modes,
        },
    }

add_flatgeobuf(self, url, name=None, layer_type=None, paint=None, fit_bounds=True, **kwargs)

Add a FlatGeobuf layer from a URL.

Streams and renders cloud-native FlatGeobuf vector data directly in the browser without downloading the entire file.

Parameters:

Name Type Description Default
url str

URL to the FlatGeobuf file.

required
name Optional[str]

Layer name. If None, auto-generated.

None
layer_type Optional[str]

MapLibre layer type ('circle', 'line', 'fill'). If None, inferred from geometry type.

None
paint Optional[Dict]

MapLibre paint properties. If None, defaults are used.

None
fit_bounds bool

Whether to fit map to data bounds.

True
**kwargs

Additional layer options.

{}

Examples:

>>> m = Map()
>>> m.add_flatgeobuf(
...     "https://flatgeobuf.org/test/data/UScounties.fgb",
...     name="counties",
...     paint={"fill-color": "#088", "fill-opacity": 0.5},
... )
Source code in anymap_ts/maplibre.py
def add_flatgeobuf(
    self,
    url: str,
    name: Optional[str] = None,
    layer_type: Optional[str] = None,
    paint: Optional[Dict] = None,
    fit_bounds: bool = True,
    **kwargs,
) -> None:
    """Add a FlatGeobuf layer from a URL.

    Streams and renders cloud-native FlatGeobuf vector data directly
    in the browser without downloading the entire file.

    Args:
        url: URL to the FlatGeobuf file.
        name: Layer name. If None, auto-generated.
        layer_type: MapLibre layer type ('circle', 'line', 'fill').
            If None, inferred from geometry type.
        paint: MapLibre paint properties. If None, defaults are used.
        fit_bounds: Whether to fit map to data bounds.
        **kwargs: Additional layer options.

    Example:
        >>> m = Map()
        >>> m.add_flatgeobuf(
        ...     "https://flatgeobuf.org/test/data/UScounties.fgb",
        ...     name="counties",
        ...     paint={"fill-color": "#088", "fill-opacity": 0.5},
        ... )
    """
    layer_id = name or f"flatgeobuf-{len(self._layers)}"

    self.call_js_method(
        "addFlatGeobuf",
        url=url,
        name=layer_id,
        layerType=layer_type,
        paint=paint,
        fitBounds=fit_bounds,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "flatgeobuf",
            "url": url,
        },
    }
    self._add_to_layer_dict(layer_id, "Vector")

add_geojson(self, data, layer_type=None, paint=None, name=None, fit_bounds=True, **kwargs)

Add GeoJSON data to the map.

Parameters:

Name Type Description Default
data Union[str, Dict]

GeoJSON dict or URL to GeoJSON file

required
layer_type Optional[str]

MapLibre layer type

None
paint Optional[Dict]

MapLibre paint properties

None
name Optional[str]

Layer name

None
fit_bounds bool

Whether to fit map to data bounds

True
**kwargs

Additional layer options

{}
Source code in anymap_ts/maplibre.py
def add_geojson(
    self,
    data: Union[str, Dict],
    layer_type: Optional[str] = None,
    paint: Optional[Dict] = None,
    name: Optional[str] = None,
    fit_bounds: bool = True,
    **kwargs,
) -> None:
    """Add GeoJSON data to the map.

    Args:
        data: GeoJSON dict or URL to GeoJSON file
        layer_type: MapLibre layer type
        paint: MapLibre paint properties
        name: Layer name
        fit_bounds: Whether to fit map to data bounds
        **kwargs: Additional layer options
    """
    self.add_vector(
        data,
        layer_type=layer_type,
        paint=paint,
        name=name,
        fit_bounds=fit_bounds,
        **kwargs,
    )

add_geojson_layer(self, data, name=None, get_fill_color=None, get_line_color=None, get_line_width=1, get_point_radius=5, get_elevation=0, extruded=False, wireframe=False, filled=True, stroked=True, line_width_min_pixels=1, point_radius_min_pixels=2, pickable=True, opacity=0.8, **kwargs)

Add a GeoJSON layer with auto-styling using deck.gl.

GeoJSON layers render GeoJSON features with automatic geometry type detection and styling, supporting points, lines, and polygons.

Parameters:

Name Type Description Default
data Any

GeoJSON object, URL, or file path.

required
name Optional[str]

Layer ID. If None, auto-generated.

None
get_fill_color Optional[Union[List[int], str]]

Accessor for fill color [r, g, b, a]. Default: [51, 136, 255, 128].

None
get_line_color Optional[Union[List[int], str]]

Accessor for stroke color [r, g, b, a]. Default: [0, 0, 0, 255].

None
get_line_width Union[float, str]

Accessor for stroke width.

1
get_point_radius Union[float, str]

Accessor for point radius.

5
get_elevation Union[float, str]

Accessor for 3D extrusion height.

0
extruded bool

Whether to render as 3D features.

False
wireframe bool

Whether to render wireframe (extruded only).

False
filled bool

Whether to fill features.

True
stroked bool

Whether to draw stroke.

True
line_width_min_pixels float

Minimum stroke width in pixels.

1
point_radius_min_pixels float

Minimum point radius in pixels.

2
pickable bool

Whether layer responds to hover/click events.

True
opacity float

Layer opacity (0-1).

0.8
**kwargs

Additional GeoJsonLayer props.

{}

Examples:

>>> from anymap_ts import MapLibreMap
>>> m = MapLibreMap()
>>> m.add_geojson_layer(
...     "https://example.com/data.geojson",
...     get_fill_color=[255, 0, 0, 128],
... )
Source code in anymap_ts/maplibre.py
def add_geojson_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_fill_color: Optional[Union[List[int], str]] = None,
    get_line_color: Optional[Union[List[int], str]] = None,
    get_line_width: Union[float, str] = 1,
    get_point_radius: Union[float, str] = 5,
    get_elevation: Union[float, str] = 0,
    extruded: bool = False,
    wireframe: bool = False,
    filled: bool = True,
    stroked: bool = True,
    line_width_min_pixels: float = 1,
    point_radius_min_pixels: float = 2,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add a GeoJSON layer with auto-styling using deck.gl.

    GeoJSON layers render GeoJSON features with automatic geometry type
    detection and styling, supporting points, lines, and polygons.

    Args:
        data: GeoJSON object, URL, or file path.
        name: Layer ID. If None, auto-generated.
        get_fill_color: Accessor for fill color [r, g, b, a].
            Default: [51, 136, 255, 128].
        get_line_color: Accessor for stroke color [r, g, b, a].
            Default: [0, 0, 0, 255].
        get_line_width: Accessor for stroke width.
        get_point_radius: Accessor for point radius.
        get_elevation: Accessor for 3D extrusion height.
        extruded: Whether to render as 3D features.
        wireframe: Whether to render wireframe (extruded only).
        filled: Whether to fill features.
        stroked: Whether to draw stroke.
        line_width_min_pixels: Minimum stroke width in pixels.
        point_radius_min_pixels: Minimum point radius in pixels.
        pickable: Whether layer responds to hover/click events.
        opacity: Layer opacity (0-1).
        **kwargs: Additional GeoJsonLayer props.

    Example:
        >>> from anymap_ts import MapLibreMap
        >>> m = MapLibreMap()
        >>> m.add_geojson_layer(
        ...     "https://example.com/data.geojson",
        ...     get_fill_color=[255, 0, 0, 128],
        ... )
    """
    layer_id = name or f"geojson-deck-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addGeoJsonLayer",
        id=layer_id,
        data=processed_data,
        getFillColor=get_fill_color or [51, 136, 255, 128],
        getLineColor=get_line_color or [0, 0, 0, 255],
        getLineWidth=get_line_width,
        getPointRadius=get_point_radius,
        getElevation=get_elevation,
        extruded=extruded,
        wireframe=wireframe,
        filled=filled,
        stroked=stroked,
        lineWidthMinPixels=line_width_min_pixels,
        pointRadiusMinPixels=point_radius_min_pixels,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "geojson-deck",
        },
    }
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_grid_cell_layer(self, data, name=None, get_position='coordinates', get_color=None, get_elevation=1000, cell_size=200, coverage=1, elevation_scale=1, extruded=True, pickable=True, opacity=0.8, **kwargs)

Add a grid cell layer for pre-aggregated grid visualization using deck.gl.

Parameters:

Name Type Description Default
data Any

Array of data objects with position coordinates.

required
name Optional[str]

Layer ID. If None, auto-generated.

None
get_position Union[str, Any]

Accessor for cell position [lng, lat].

'coordinates'
get_color Optional[Union[List[int], str]]

Accessor for cell color [r, g, b, a].

None
get_elevation Union[float, str]

Accessor for cell height.

1000
cell_size float

Cell size in meters.

200
coverage float

Cell coverage (0-1).

1
elevation_scale float

Elevation multiplier.

1
extruded bool

Whether to extrude cells.

True
pickable bool

Whether layer responds to hover/click events.

True
opacity float

Layer opacity (0-1).

0.8
**kwargs

Additional GridCellLayer props.

{}

Examples:

>>> from anymap_ts import MapLibreMap
>>> m = MapLibreMap(pitch=45)
>>> data = [
...     {"coordinates": [-122.4, 37.8], "value": 500},
... ]
>>> m.add_grid_cell_layer(data, get_elevation="value")
Source code in anymap_ts/maplibre.py
def add_grid_cell_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_position: Union[str, Any] = "coordinates",
    get_color: Optional[Union[List[int], str]] = None,
    get_elevation: Union[float, str] = 1000,
    cell_size: float = 200,
    coverage: float = 1,
    elevation_scale: float = 1,
    extruded: bool = True,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add a grid cell layer for pre-aggregated grid visualization using deck.gl.

    Args:
        data: Array of data objects with position coordinates.
        name: Layer ID. If None, auto-generated.
        get_position: Accessor for cell position [lng, lat].
        get_color: Accessor for cell color [r, g, b, a].
        get_elevation: Accessor for cell height.
        cell_size: Cell size in meters.
        coverage: Cell coverage (0-1).
        elevation_scale: Elevation multiplier.
        extruded: Whether to extrude cells.
        pickable: Whether layer responds to hover/click events.
        opacity: Layer opacity (0-1).
        **kwargs: Additional GridCellLayer props.

    Example:
        >>> from anymap_ts import MapLibreMap
        >>> m = MapLibreMap(pitch=45)
        >>> data = [
        ...     {"coordinates": [-122.4, 37.8], "value": 500},
        ... ]
        >>> m.add_grid_cell_layer(data, get_elevation="value")
    """
    layer_id = name or f"gridcell-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addGridCellLayer",
        id=layer_id,
        data=processed_data,
        getPosition=get_position,
        getColor=get_color or [255, 140, 0, 200],
        getElevation=get_elevation,
        cellSize=cell_size,
        coverage=coverage,
        elevationScale=elevation_scale,
        extruded=extruded,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {"id": layer_id, "type": "gridcell"},
    }
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_grid_layer(self, data, name=None, get_position='coordinates', cell_size=200, elevation_scale=4, extruded=True, color_range=None, pickable=True, opacity=0.8, **kwargs)

Add a grid layer for square grid aggregation using deck.gl.

Grid layers aggregate points into square grid cells and render them with height and color based on point density.

Parameters:

Name Type Description Default
data Any

Array of data objects with position coordinates.

required
name Optional[str]

Layer ID. If None, auto-generated.

None
get_position Union[str, Any]

Accessor for point position [lng, lat].

'coordinates'
cell_size float

Grid cell size in meters.

200
elevation_scale float

Elevation multiplier for 3D cells.

4
extruded bool

Whether to render as 3D cells.

True
color_range Optional[List[List[int]]]

Color gradient [[r, g, b], ...].

None
pickable bool

Whether layer responds to hover/click events.

True
opacity float

Layer opacity (0-1).

0.8
**kwargs

Additional GridLayer props.

{}

Examples:

>>> from anymap_ts import MapLibreMap
>>> m = MapLibreMap(pitch=45)
>>> points = [
...     {"coordinates": [-122.4, 37.8]},
...     {"coordinates": [-122.41, 37.81]},
... ]
>>> m.add_grid_layer(points, cell_size=500)
Source code in anymap_ts/maplibre.py
def add_grid_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_position: Union[str, Any] = "coordinates",
    cell_size: float = 200,
    elevation_scale: float = 4,
    extruded: bool = True,
    color_range: Optional[List[List[int]]] = None,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add a grid layer for square grid aggregation using deck.gl.

    Grid layers aggregate points into square grid cells and render them
    with height and color based on point density.

    Args:
        data: Array of data objects with position coordinates.
        name: Layer ID. If None, auto-generated.
        get_position: Accessor for point position [lng, lat].
        cell_size: Grid cell size in meters.
        elevation_scale: Elevation multiplier for 3D cells.
        extruded: Whether to render as 3D cells.
        color_range: Color gradient [[r, g, b], ...].
        pickable: Whether layer responds to hover/click events.
        opacity: Layer opacity (0-1).
        **kwargs: Additional GridLayer props.

    Example:
        >>> from anymap_ts import MapLibreMap
        >>> m = MapLibreMap(pitch=45)
        >>> points = [
        ...     {"coordinates": [-122.4, 37.8]},
        ...     {"coordinates": [-122.41, 37.81]},
        ... ]
        >>> m.add_grid_layer(points, cell_size=500)
    """
    layer_id = name or f"grid-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    default_color_range = [
        [1, 152, 189],
        [73, 227, 206],
        [216, 254, 181],
        [254, 237, 177],
        [254, 173, 84],
        [209, 55, 78],
    ]

    self.call_js_method(
        "addGridLayer",
        id=layer_id,
        data=processed_data,
        getPosition=get_position,
        cellSize=cell_size,
        elevationScale=elevation_scale,
        extruded=extruded,
        colorRange=color_range or default_color_range,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "grid",
        },
    }
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_heatmap(self, data, weight_property=None, radius=20, intensity=1.0, colormap=None, opacity=0.8, name=None, fit_bounds=True, **kwargs)

Add a heatmap layer to the map.

Creates a heatmap visualization from point data using MapLibre's native heatmap layer type.

Parameters:

Name Type Description Default
data Any

Point data - can be GeoJSON, GeoDataFrame, or file path.

required
weight_property Optional[str]

Property name to use for point weights. If None, all points have equal weight.

None
radius int

Radius of influence for each point in pixels.

20
intensity float

Intensity multiplier for the heatmap.

1.0
colormap Optional[List]

Color gradient as list of [stop, color] pairs. Example: [[0, "blue"], [0.5, "yellow"], [1, "red"]] Default: blue-yellow-red gradient.

None
opacity float

Layer opacity (0-1).

0.8
name Optional[str]

Layer identifier. If None, auto-generated.

None
fit_bounds bool

Whether to fit map to data bounds.

True
**kwargs

Additional heatmap layer options.

{}

Examples:

>>> from anymap_ts import Map
>>> m = Map()
>>> m.add_heatmap(
...     "earthquakes.geojson",
...     weight_property="magnitude",
...     radius=30,
...     colormap=[[0, "blue"], [0.5, "lime"], [1, "red"]]
... )
Source code in anymap_ts/maplibre.py
def add_heatmap(
    self,
    data: Any,
    weight_property: Optional[str] = None,
    radius: int = 20,
    intensity: float = 1.0,
    colormap: Optional[List] = None,
    opacity: float = 0.8,
    name: Optional[str] = None,
    fit_bounds: bool = True,
    **kwargs,
) -> None:
    """Add a heatmap layer to the map.

    Creates a heatmap visualization from point data using MapLibre's
    native heatmap layer type.

    Args:
        data: Point data - can be GeoJSON, GeoDataFrame, or file path.
        weight_property: Property name to use for point weights.
            If None, all points have equal weight.
        radius: Radius of influence for each point in pixels.
        intensity: Intensity multiplier for the heatmap.
        colormap: Color gradient as list of [stop, color] pairs.
            Example: [[0, "blue"], [0.5, "yellow"], [1, "red"]]
            Default: blue-yellow-red gradient.
        opacity: Layer opacity (0-1).
        name: Layer identifier. If None, auto-generated.
        fit_bounds: Whether to fit map to data bounds.
        **kwargs: Additional heatmap layer options.

    Example:
        >>> from anymap_ts import Map
        >>> m = Map()
        >>> m.add_heatmap(
        ...     "earthquakes.geojson",
        ...     weight_property="magnitude",
        ...     radius=30,
        ...     colormap=[[0, "blue"], [0.5, "lime"], [1, "red"]]
        ... )
    """
    self._validate_opacity(opacity)
    layer_id = name or f"heatmap-{len(self._layers)}"

    # Convert data to GeoJSON
    geojson = to_geojson(data)

    # Handle URL data - fetch GeoJSON
    if geojson.get("type") == "url":
        url = geojson["url"]
        geojson = fetch_geojson(url)

    # Default colormap
    if colormap is None:
        colormap = [
            [0, "rgba(33,102,172,0)"],
            [0.2, "rgb(103,169,207)"],
            [0.4, "rgb(209,229,240)"],
            [0.6, "rgb(253,219,199)"],
            [0.8, "rgb(239,138,98)"],
            [1, "rgb(178,24,43)"],
        ]

    # Build heatmap paint properties
    paint = {
        "heatmap-radius": radius,
        "heatmap-intensity": intensity,
        "heatmap-opacity": opacity,
        "heatmap-color": [
            "interpolate",
            ["linear"],
            ["heatmap-density"],
        ],
    }

    # Add colormap stops
    for stop, color in colormap:
        paint["heatmap-color"].extend([stop, color])

    # Add weight if specified
    if weight_property:
        paint["heatmap-weight"] = ["get", weight_property]

    # Get bounds
    bounds = get_bounds(geojson) if fit_bounds else None

    self.call_js_method(
        "addGeoJSON",
        data=geojson,
        name=layer_id,
        layerType="heatmap",
        paint=paint,
        fitBounds=fit_bounds,
        bounds=bounds,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "heatmap",
            "source": f"{layer_id}-source",
            "paint": paint,
        },
    }
    self._add_to_layer_dict(layer_id, "Heatmap")

add_hexagon_layer(self, data, name=None, get_position='coordinates', radius=1000, elevation_scale=4, extruded=True, color_range=None, pickable=True, opacity=0.8, **kwargs)

Add a hexagon layer for hexagonal binning/aggregation using deck.gl.

Hexagon layers aggregate points into hexagonal bins and render them with height and color based on point density.

Parameters:

Name Type Description Default
data Any

Array of data objects with position coordinates.

required
name Optional[str]

Layer ID. If None, auto-generated.

None
get_position Union[str, Any]

Accessor for point position [lng, lat].

'coordinates'
radius float

Hexagon radius in meters.

1000
elevation_scale float

Elevation multiplier for 3D hexagons.

4
extruded bool

Whether to render as 3D hexagons.

True
color_range Optional[List[List[int]]]

Color gradient for aggregation [[r, g, b], ...].

None
pickable bool

Whether layer responds to hover/click events.

True
opacity float

Layer opacity (0-1).

0.8
**kwargs

Additional HexagonLayer props.

{}

Examples:

>>> from anymap_ts import MapLibreMap
>>> m = MapLibreMap(pitch=45)
>>> points = [
...     {"coordinates": [-122.4, 37.8]},
...     {"coordinates": [-122.41, 37.81]},
... ]
>>> m.add_hexagon_layer(points, radius=500, elevation_scale=10)
Source code in anymap_ts/maplibre.py
def add_hexagon_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_position: Union[str, Any] = "coordinates",
    radius: float = 1000,
    elevation_scale: float = 4,
    extruded: bool = True,
    color_range: Optional[List[List[int]]] = None,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add a hexagon layer for hexagonal binning/aggregation using deck.gl.

    Hexagon layers aggregate points into hexagonal bins and render them
    with height and color based on point density.

    Args:
        data: Array of data objects with position coordinates.
        name: Layer ID. If None, auto-generated.
        get_position: Accessor for point position [lng, lat].
        radius: Hexagon radius in meters.
        elevation_scale: Elevation multiplier for 3D hexagons.
        extruded: Whether to render as 3D hexagons.
        color_range: Color gradient for aggregation [[r, g, b], ...].
        pickable: Whether layer responds to hover/click events.
        opacity: Layer opacity (0-1).
        **kwargs: Additional HexagonLayer props.

    Example:
        >>> from anymap_ts import MapLibreMap
        >>> m = MapLibreMap(pitch=45)
        >>> points = [
        ...     {"coordinates": [-122.4, 37.8]},
        ...     {"coordinates": [-122.41, 37.81]},
        ... ]
        >>> m.add_hexagon_layer(points, radius=500, elevation_scale=10)
    """
    layer_id = name or f"hexagon-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    default_color_range = [
        [1, 152, 189],
        [73, 227, 206],
        [216, 254, 181],
        [254, 237, 177],
        [254, 173, 84],
        [209, 55, 78],
    ]

    self.call_js_method(
        "addHexagonLayer",
        id=layer_id,
        data=processed_data,
        getPosition=get_position,
        radius=radius,
        elevationScale=elevation_scale,
        extruded=extruded,
        colorRange=color_range or default_color_range,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "hexagon",
        },
    }
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_hover_effect(self, layer_id, highlight_color=None, highlight_opacity=None, highlight_outline_width=2, **kwargs)

Add hover highlight effect to an existing layer.

When the mouse hovers over a feature, it will be highlighted with the specified styles.

Parameters:

Name Type Description Default
layer_id str

Layer identifier to add hover effect to.

required
highlight_color Optional[str]

Override fill/line color on hover. If None, the original color is kept but opacity/outline changes.

None
highlight_opacity Optional[float]

Override opacity on hover.

None
highlight_outline_width float

Outline width on hover.

2
**kwargs

Additional hover effect options.

{}

Examples:

>>> from anymap_ts import Map
>>> m = Map()
>>> m.add_geojson("states.geojson", name="states")
>>> m.add_hover_effect("states", highlight_opacity=0.9)
Source code in anymap_ts/maplibre.py
def add_hover_effect(
    self,
    layer_id: str,
    highlight_color: Optional[str] = None,
    highlight_opacity: Optional[float] = None,
    highlight_outline_width: float = 2,
    **kwargs,
) -> None:
    """Add hover highlight effect to an existing layer.

    When the mouse hovers over a feature, it will be highlighted with
    the specified styles.

    Args:
        layer_id: Layer identifier to add hover effect to.
        highlight_color: Override fill/line color on hover. If None,
            the original color is kept but opacity/outline changes.
        highlight_opacity: Override opacity on hover.
        highlight_outline_width: Outline width on hover.
        **kwargs: Additional hover effect options.

    Example:
        >>> from anymap_ts import Map
        >>> m = Map()
        >>> m.add_geojson("states.geojson", name="states")
        >>> m.add_hover_effect("states", highlight_opacity=0.9)
    """
    self.call_js_method(
        "addHoverEffect",
        layerId=layer_id,
        highlightColor=highlight_color,
        highlightOpacity=highlight_opacity,
        highlightOutlineWidth=highlight_outline_width,
        **kwargs,
    )

add_icon_layer(self, data, name=None, get_position='coordinates', get_icon='icon', get_size=20, get_color=None, icon_atlas=None, icon_mapping=None, pickable=True, opacity=1, **kwargs)

Add an icon layer for custom icon markers at scale using deck.gl.

Icon layers render icons/images at specified positions, ideal for rendering large numbers of custom markers efficiently.

Parameters:

Name Type Description Default
data Any

Array of data objects with position coordinates.

required
name Optional[str]

Layer ID. If None, auto-generated.

None
get_position Union[str, Any]

Accessor for icon position [lng, lat].

'coordinates'
get_icon Union[str, Any]

Accessor for icon name in icon_mapping.

'icon'
get_size Union[float, str]

Accessor for icon size in pixels.

20
get_color Optional[Union[List[int], str]]

Accessor for icon tint color [r, g, b, a]. Default: [255, 255, 255, 255] (white, no tint).

None
icon_atlas Optional[str]

URL to icon atlas image.

None
icon_mapping Optional[Dict]

Dict mapping icon names to atlas coordinates.

None
pickable bool

Whether layer responds to hover/click events.

True
opacity float

Layer opacity (0-1).

1
**kwargs

Additional IconLayer props.

{}

Examples:

>>> from anymap_ts import MapLibreMap
>>> m = MapLibreMap()
>>> markers = [
...     {"coordinates": [-122.4, 37.8], "icon": "marker", "size": 30},
... ]
>>> m.add_icon_layer(markers, get_size="size")
Source code in anymap_ts/maplibre.py
def add_icon_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_position: Union[str, Any] = "coordinates",
    get_icon: Union[str, Any] = "icon",
    get_size: Union[float, str] = 20,
    get_color: Optional[Union[List[int], str]] = None,
    icon_atlas: Optional[str] = None,
    icon_mapping: Optional[Dict] = None,
    pickable: bool = True,
    opacity: float = 1,
    **kwargs,
) -> None:
    """Add an icon layer for custom icon markers at scale using deck.gl.

    Icon layers render icons/images at specified positions, ideal for
    rendering large numbers of custom markers efficiently.

    Args:
        data: Array of data objects with position coordinates.
        name: Layer ID. If None, auto-generated.
        get_position: Accessor for icon position [lng, lat].
        get_icon: Accessor for icon name in icon_mapping.
        get_size: Accessor for icon size in pixels.
        get_color: Accessor for icon tint color [r, g, b, a].
            Default: [255, 255, 255, 255] (white, no tint).
        icon_atlas: URL to icon atlas image.
        icon_mapping: Dict mapping icon names to atlas coordinates.
        pickable: Whether layer responds to hover/click events.
        opacity: Layer opacity (0-1).
        **kwargs: Additional IconLayer props.

    Example:
        >>> from anymap_ts import MapLibreMap
        >>> m = MapLibreMap()
        >>> markers = [
        ...     {"coordinates": [-122.4, 37.8], "icon": "marker", "size": 30},
        ... ]
        >>> m.add_icon_layer(markers, get_size="size")
    """
    layer_id = name or f"icon-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addIconLayer",
        id=layer_id,
        data=processed_data,
        getPosition=get_position,
        getIcon=get_icon,
        getSize=get_size,
        getColor=get_color or [255, 255, 255, 255],
        iconAtlas=icon_atlas,
        iconMapping=icon_mapping,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "icon",
        },
    }
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_image(self, name, url)

Load a custom icon image for use in symbol layers.

Parameters:

Name Type Description Default
name str

Name to reference this image in symbol layers.

required
url str

URL to the image file (PNG, JPEG, etc.).

required

Examples:

>>> m = MapLibreMap()
>>> m.add_image("custom-marker", "https://example.com/marker.png")
Source code in anymap_ts/maplibre.py
def add_image(self, name: str, url: str) -> None:
    """Load a custom icon image for use in symbol layers.

    Args:
        name: Name to reference this image in symbol layers.
        url: URL to the image file (PNG, JPEG, etc.).

    Example:
        >>> m = MapLibreMap()
        >>> m.add_image("custom-marker", "https://example.com/marker.png")
    """
    self.call_js_method("addMapImage", name=name, url=url)

add_image_layer(self, url, coordinates, name=None, opacity=1.0, **kwargs)

Add a georeferenced image overlay.

Overlays an image on the map at specified geographic coordinates.

Parameters:

Name Type Description Default
url str

URL to the image file.

required
coordinates List[List[float]]

Four corner coordinates as [[lng, lat], ...] in order: top-left, top-right, bottom-right, bottom-left.

required
name Optional[str]

Layer identifier. If None, auto-generated.

None
opacity float

Layer opacity (0-1).

1.0
**kwargs

Additional layer options.

{}

Examples:

>>> from anymap_ts import Map
>>> m = Map()
>>> m.add_image_layer(
...     url="https://example.com/overlay.png",
...     coordinates=[
...         [-80.425, 46.437],  # top-left
...         [-71.516, 46.437],  # top-right
...         [-71.516, 37.936],  # bottom-right
...         [-80.425, 37.936],  # bottom-left
...     ]
... )
Source code in anymap_ts/maplibre.py
def add_image_layer(
    self,
    url: str,
    coordinates: List[List[float]],
    name: Optional[str] = None,
    opacity: float = 1.0,
    **kwargs,
) -> None:
    """Add a georeferenced image overlay.

    Overlays an image on the map at specified geographic coordinates.

    Args:
        url: URL to the image file.
        coordinates: Four corner coordinates as [[lng, lat], ...] in order:
            top-left, top-right, bottom-right, bottom-left.
        name: Layer identifier. If None, auto-generated.
        opacity: Layer opacity (0-1).
        **kwargs: Additional layer options.

    Example:
        >>> from anymap_ts import Map
        >>> m = Map()
        >>> m.add_image_layer(
        ...     url="https://example.com/overlay.png",
        ...     coordinates=[
        ...         [-80.425, 46.437],  # top-left
        ...         [-71.516, 46.437],  # top-right
        ...         [-71.516, 37.936],  # bottom-right
        ...         [-80.425, 37.936],  # bottom-left
        ...     ]
        ... )
    """
    self._validate_opacity(opacity)
    layer_id = name or f"image-{len(self._layers)}"

    if len(coordinates) != 4:
        raise ValueError(
            "coordinates must have exactly 4 corner points "
            "[top-left, top-right, bottom-right, bottom-left]"
        )

    self.call_js_method(
        "addImageLayer",
        id=layer_id,
        url=url,
        coordinates=coordinates,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "image",
            "url": url,
            "coordinates": coordinates,
        },
    }
    self._add_to_layer_dict(layer_id, "Raster")

add_layer(self, layer_id, layer_type, source, paint=None, layout=None, before_id=None, **kwargs)

Add a generic layer to the map.

Parameters:

Name Type Description Default
layer_id str

Unique layer identifier

required
layer_type str

MapLibre layer type

required
source Union[str, Dict]

Source ID or source configuration dict

required
paint Optional[Dict]

Paint properties

None
layout Optional[Dict]

Layout properties

None
before_id Optional[str]

ID of layer to insert before

None
**kwargs

Additional layer options

{}
Source code in anymap_ts/maplibre.py
def add_layer(
    self,
    layer_id: str,
    layer_type: str,
    source: Union[str, Dict],
    paint: Optional[Dict] = None,
    layout: Optional[Dict] = None,
    before_id: Optional[str] = None,
    **kwargs,
) -> None:
    """Add a generic layer to the map.

    Args:
        layer_id: Unique layer identifier
        layer_type: MapLibre layer type
        source: Source ID or source configuration dict
        paint: Paint properties
        layout: Layout properties
        before_id: ID of layer to insert before
        **kwargs: Additional layer options
    """
    layer_config = {
        "id": layer_id,
        "type": layer_type,
        "paint": paint or {},
        "layout": layout or {},
        **kwargs,
    }

    if isinstance(source, str):
        layer_config["source"] = source
    else:
        source_id = f"{layer_id}-source"
        self._sources = {**self._sources, source_id: source}
        self.call_js_method("addSource", source_id, **source)
        layer_config["source"] = source_id

    self._layers = {**self._layers, layer_id: layer_config}
    self.call_js_method("addLayer", beforeId=before_id, **layer_config)
    # Determine category based on layer type
    layer_type = layer_config.get("type", "")
    if layer_type == "raster":
        self._add_to_layer_dict(layer_id, "Raster")
    else:
        self._add_to_layer_dict(layer_id, "Vector")

add_layer_control(self, layers=None, position='top-right', collapsed=True)

Add a layer visibility control.

Uses maplibre-gl-layer-control for layer toggling and opacity.

Parameters:

Name Type Description Default
layers Optional[List[str]]

List of layer IDs to include (None = all layers)

None
position str

Control position

'top-right'
collapsed bool

Whether control starts collapsed

True
Source code in anymap_ts/maplibre.py
def add_layer_control(
    self,
    layers: Optional[List[str]] = None,
    position: str = "top-right",
    collapsed: bool = True,
) -> None:
    """Add a layer visibility control.

    Uses maplibre-gl-layer-control for layer toggling and opacity.

    Args:
        layers: List of layer IDs to include (None = all layers)
        position: Control position
        collapsed: Whether control starts collapsed
    """
    if layers is None:
        layers = list(self._layers.keys())

    self.call_js_method(
        "addLayerControl",
        layers=layers,
        position=position,
        collapsed=collapsed,
    )
    self._controls = {
        **self._controls,
        "layer-control": {
            "layers": layers,
            "position": position,
            "collapsed": collapsed,
        },
    }

add_legend(self, title, labels, colors, position='bottom-right', opacity=1.0, legend_id=None, **kwargs)

Add a floating legend control to the map.

Creates a custom legend control with colored boxes and labels that floats over the map in the specified position.

Parameters:

Name Type Description Default
title str

Legend title text

required
labels List[str]

List of label strings for each legend item

required
colors List[str]

List of hex color strings (e.g., ['#ff0000', '#00ff00', '#0000ff'])

required
position str

Legend position ('top-left', 'top-right', 'bottom-left', 'bottom-right')

'bottom-right'
opacity float

Legend background opacity (0-1)

1.0
legend_id Optional[str]

Custom legend identifier (auto-generated if None)

None
**kwargs

Additional legend styling options

{}

Examples:

>>> from anymap_ts import Map
>>> m = Map()
>>> m.add_legend(
...     title="Land Cover",
...     labels=["Forest", "Water", "Urban"],
...     colors=["#228B22", "#0000FF", "#808080"],
...     position="top-left"
... )
Source code in anymap_ts/maplibre.py
def add_legend(
    self,
    title: str,
    labels: List[str],
    colors: List[str],
    position: str = "bottom-right",
    opacity: float = 1.0,
    legend_id: Optional[str] = None,
    **kwargs,
) -> None:
    """Add a floating legend control to the map.

    Creates a custom legend control with colored boxes and labels that
    floats over the map in the specified position.

    Args:
        title: Legend title text
        labels: List of label strings for each legend item
        colors: List of hex color strings (e.g., ['#ff0000', '#00ff00', '#0000ff'])
        position: Legend position ('top-left', 'top-right', 'bottom-left', 'bottom-right')
        opacity: Legend background opacity (0-1)
        legend_id: Custom legend identifier (auto-generated if None)
        **kwargs: Additional legend styling options

    Example:
        >>> from anymap_ts import Map
        >>> m = Map()
        >>> m.add_legend(
        ...     title="Land Cover",
        ...     labels=["Forest", "Water", "Urban"],
        ...     colors=["#228B22", "#0000FF", "#808080"],
        ...     position="top-left"
        ... )
    """
    if len(labels) != len(colors):
        raise ValueError("Number of labels must match number of colors")

    # Validate position
    self._validate_position(position)

    # Validate colors (basic hex color check)
    for i, color in enumerate(colors):
        if not isinstance(color, str) or not color.startswith("#"):
            raise ValueError(
                f"Color at index {i} must be a hex color string (e.g., '#ff0000')"
            )

    legend_id = (
        legend_id
        or f"legend-{len([k for k in self._controls.keys() if k.startswith('legend')])}"
    )

    # Prepare legend data
    legend_items = []
    for label, color in zip(labels, colors):
        legend_items.append(
            {
                "label": label,
                "color": color,
            }
        )

    # Call JavaScript method to add legend
    self.call_js_method(
        "addLegend",
        id=legend_id,
        title=title,
        items=legend_items,
        position=position,
        opacity=opacity,
        **kwargs,
    )

    # Track legend control
    self._controls = {
        **self._controls,
        legend_id: {
            "type": "legend",
            "title": title,
            "labels": labels,
            "colors": colors,
            "position": position,
            "opacity": opacity,
        },
    }

add_lidar_control(self, position='top-right', collapsed=True, title='LiDAR Viewer', point_size=2, opacity=1.0, color_scheme='elevation', use_percentile=True, point_budget=1000000, pickable=False, auto_zoom=True, copc_loading_mode=None, streaming_point_budget=5000000, panel_max_height=600, **kwargs)

Add an interactive LiDAR control panel.

The LiDAR control provides a UI panel for loading, visualizing, and styling LiDAR point cloud files (LAS, LAZ, COPC formats).

Parameters:

Name Type Description Default
position str

Control position ('top-left', 'top-right', 'bottom-left', 'bottom-right').

'top-right'
collapsed bool

Whether the panel starts collapsed.

True
title str

Title displayed on the panel.

'LiDAR Viewer'
point_size float

Point size in pixels.

2
opacity float

Layer opacity (0-1).

1.0
color_scheme str

Color scheme ('elevation', 'intensity', 'classification', 'rgb').

'elevation'
use_percentile bool

Use 2-98% percentile for color scaling.

True
point_budget int

Maximum number of points to display.

1000000
pickable bool

Enable hover/click interactions.

False
auto_zoom bool

Auto-zoom to point cloud after loading.

True
copc_loading_mode Optional[str]

COPC loading mode ('full' or 'dynamic').

None
streaming_point_budget int

Point budget for streaming mode.

5000000
panel_max_height int

Maximum height of the panel in pixels.

600
**kwargs

Additional control options.

{}

Examples:

>>> from anymap_ts import MapLibreMap
>>> m = MapLibreMap(pitch=60)
>>> m.add_lidar_control(color_scheme="classification", pickable=True)
Source code in anymap_ts/maplibre.py
def add_lidar_control(
    self,
    position: str = "top-right",
    collapsed: bool = True,
    title: str = "LiDAR Viewer",
    point_size: float = 2,
    opacity: float = 1.0,
    color_scheme: str = "elevation",
    use_percentile: bool = True,
    point_budget: int = 1000000,
    pickable: bool = False,
    auto_zoom: bool = True,
    copc_loading_mode: Optional[str] = None,
    streaming_point_budget: int = 5000000,
    panel_max_height: int = 600,
    **kwargs,
) -> None:
    """Add an interactive LiDAR control panel.

    The LiDAR control provides a UI panel for loading, visualizing, and
    styling LiDAR point cloud files (LAS, LAZ, COPC formats).

    Args:
        position: Control position ('top-left', 'top-right', 'bottom-left', 'bottom-right').
        collapsed: Whether the panel starts collapsed.
        title: Title displayed on the panel.
        point_size: Point size in pixels.
        opacity: Layer opacity (0-1).
        color_scheme: Color scheme ('elevation', 'intensity', 'classification', 'rgb').
        use_percentile: Use 2-98% percentile for color scaling.
        point_budget: Maximum number of points to display.
        pickable: Enable hover/click interactions.
        auto_zoom: Auto-zoom to point cloud after loading.
        copc_loading_mode: COPC loading mode ('full' or 'dynamic').
        streaming_point_budget: Point budget for streaming mode.
        panel_max_height: Maximum height of the panel in pixels.
        **kwargs: Additional control options.

    Example:
        >>> from anymap_ts import MapLibreMap
        >>> m = MapLibreMap(pitch=60)
        >>> m.add_lidar_control(color_scheme="classification", pickable=True)
    """
    self.call_js_method(
        "addLidarControl",
        position=position,
        collapsed=collapsed,
        title=title,
        pointSize=point_size,
        opacity=opacity,
        colorScheme=color_scheme,
        usePercentile=use_percentile,
        pointBudget=point_budget,
        pickable=pickable,
        autoZoom=auto_zoom,
        copcLoadingMode=copc_loading_mode,
        streamingPointBudget=streaming_point_budget,
        panelMaxHeight=panel_max_height,
        **kwargs,
    )
    self._controls = {
        **self._controls,
        "lidar-control": {"position": position, "collapsed": collapsed},
    }

add_lidar_layer(self, source, name=None, color_scheme='elevation', point_size=2, opacity=1.0, pickable=True, auto_zoom=True, streaming_mode=True, point_budget=1000000, **kwargs)

Load and display a LiDAR file from URL or local path.

Supports LAS, LAZ, and COPC (Cloud-Optimized Point Cloud) formats. For local files, the file is read and sent as base64 to JavaScript. For URLs, the data is loaded directly via streaming when possible.

Parameters:

Name Type Description Default
source Union[str, Path]

URL or local file path to the LiDAR file.

required
name Optional[str]

Layer identifier. If None, auto-generated.

None
color_scheme str

Color scheme ('elevation', 'intensity', 'classification', 'rgb').

'elevation'
point_size float

Point size in pixels.

2
opacity float

Layer opacity (0-1).

1.0
pickable bool

Enable hover/click interactions.

True
auto_zoom bool

Auto-zoom to point cloud after loading.

True
streaming_mode bool

Use streaming mode for large COPC files.

True
point_budget int

Maximum number of points to display.

1000000
**kwargs

Additional layer options.

{}

Examples:

>>> from anymap_ts import MapLibreMap
>>> m = MapLibreMap(center=[-123.07, 44.05], zoom=14, pitch=60)
>>> m.add_lidar_layer(
...     source="https://s3.amazonaws.com/hobu-lidar/autzen-classified.copc.laz",
...     name="autzen",
...     color_scheme="classification",
... )
Source code in anymap_ts/maplibre.py
def add_lidar_layer(
    self,
    source: Union[str, Path],
    name: Optional[str] = None,
    color_scheme: str = "elevation",
    point_size: float = 2,
    opacity: float = 1.0,
    pickable: bool = True,
    auto_zoom: bool = True,
    streaming_mode: bool = True,
    point_budget: int = 1000000,
    **kwargs,
) -> None:
    """Load and display a LiDAR file from URL or local path.

    Supports LAS, LAZ, and COPC (Cloud-Optimized Point Cloud) formats.
    For local files, the file is read and sent as base64 to JavaScript.
    For URLs, the data is loaded directly via streaming when possible.

    Args:
        source: URL or local file path to the LiDAR file.
        name: Layer identifier. If None, auto-generated.
        color_scheme: Color scheme ('elevation', 'intensity', 'classification', 'rgb').
        point_size: Point size in pixels.
        opacity: Layer opacity (0-1).
        pickable: Enable hover/click interactions.
        auto_zoom: Auto-zoom to point cloud after loading.
        streaming_mode: Use streaming mode for large COPC files.
        point_budget: Maximum number of points to display.
        **kwargs: Additional layer options.

    Example:
        >>> from anymap_ts import MapLibreMap
        >>> m = MapLibreMap(center=[-123.07, 44.05], zoom=14, pitch=60)
        >>> m.add_lidar_layer(
        ...     source="https://s3.amazonaws.com/hobu-lidar/autzen-classified.copc.laz",
        ...     name="autzen",
        ...     color_scheme="classification",
        ... )
    """
    layer_id = name or f"lidar-{len(self._layers)}"

    # Check if source is a local file
    source_path = Path(source) if isinstance(source, (str, Path)) else None
    is_local = source_path is not None and source_path.exists()

    if is_local:
        # Read local file and encode as base64
        import base64

        with open(source_path, "rb") as f:
            file_data = f.read()
        source_b64 = base64.b64encode(file_data).decode("utf-8")

        self.call_js_method(
            "addLidarLayer",
            source=source_b64,
            name=layer_id,
            isBase64=True,
            filename=source_path.name,
            colorScheme=color_scheme,
            pointSize=point_size,
            opacity=opacity,
            pickable=pickable,
            autoZoom=auto_zoom,
            streamingMode=streaming_mode,
            pointBudget=point_budget,
            **kwargs,
        )
    else:
        # Load from URL
        self.call_js_method(
            "addLidarLayer",
            source=str(source),
            name=layer_id,
            isBase64=False,
            colorScheme=color_scheme,
            pointSize=point_size,
            opacity=opacity,
            pickable=pickable,
            autoZoom=auto_zoom,
            streamingMode=streaming_mode,
            pointBudget=point_budget,
            **kwargs,
        )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "lidar",
            "source": str(source),
        },
    }
    self._add_to_layer_dict(layer_id, "LiDAR")

add_line_layer(self, data, name=None, get_source_position='sourcePosition', get_target_position='targetPosition', get_color=None, get_width=1, width_min_pixels=1, pickable=True, opacity=0.8, **kwargs)

Add a line layer for origin-destination line visualization using deck.gl.

Line layers render straight line segments between source and target positions. Unlike arc layers, lines are drawn without curvature.

Parameters:

Name Type Description Default
data Any

Array of line objects with source/target positions.

required
name Optional[str]

Layer ID. If None, auto-generated.

None
get_source_position Union[str, Any]

Accessor for source position [lng, lat].

'sourcePosition'
get_target_position Union[str, Any]

Accessor for target position [lng, lat].

'targetPosition'
get_color Optional[Union[List[int], str]]

Accessor for line color [r, g, b] or [r, g, b, a]. Default: [51, 136, 255, 200] (blue).

None
get_width Union[float, str]

Accessor for line width.

1
width_min_pixels float

Minimum line width in pixels.

1
pickable bool

Whether layer responds to hover/click events.

True
opacity float

Layer opacity (0-1).

0.8
**kwargs

Additional LineLayer props.

{}

Examples:

>>> from anymap_ts import MapLibreMap
>>> m = MapLibreMap()
>>> lines = [
...     {"sourcePosition": [-122.4, 37.8], "targetPosition": [-73.9, 40.7]},
... ]
>>> m.add_line_layer(lines, get_color=[0, 128, 255], get_width=2)
Source code in anymap_ts/maplibre.py
def add_line_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_source_position: Union[str, Any] = "sourcePosition",
    get_target_position: Union[str, Any] = "targetPosition",
    get_color: Optional[Union[List[int], str]] = None,
    get_width: Union[float, str] = 1,
    width_min_pixels: float = 1,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add a line layer for origin-destination line visualization using deck.gl.

    Line layers render straight line segments between source and target
    positions. Unlike arc layers, lines are drawn without curvature.

    Args:
        data: Array of line objects with source/target positions.
        name: Layer ID. If None, auto-generated.
        get_source_position: Accessor for source position [lng, lat].
        get_target_position: Accessor for target position [lng, lat].
        get_color: Accessor for line color [r, g, b] or [r, g, b, a].
            Default: [51, 136, 255, 200] (blue).
        get_width: Accessor for line width.
        width_min_pixels: Minimum line width in pixels.
        pickable: Whether layer responds to hover/click events.
        opacity: Layer opacity (0-1).
        **kwargs: Additional LineLayer props.

    Example:
        >>> from anymap_ts import MapLibreMap
        >>> m = MapLibreMap()
        >>> lines = [
        ...     {"sourcePosition": [-122.4, 37.8], "targetPosition": [-73.9, 40.7]},
        ... ]
        >>> m.add_line_layer(lines, get_color=[0, 128, 255], get_width=2)
    """
    layer_id = name or f"line-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addLineLayer",
        id=layer_id,
        data=processed_data,
        getSourcePosition=get_source_position,
        getTargetPosition=get_target_position,
        getColor=get_color or [51, 136, 255, 200],
        getWidth=get_width,
        widthMinPixels=width_min_pixels,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "line",
        },
    }
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_marker(self, lng, lat, popup=None, tooltip=None, color='#3388ff', draggable=False, scale=1.0, popup_max_width='240px', tooltip_max_width='240px', name=None, **kwargs)

Add a single marker to the map.

Parameters:

Name Type Description Default
lng float

Longitude of the marker.

required
lat float

Latitude of the marker.

required
popup Optional[str]

Optional popup HTML content (shown on click).

None
tooltip Optional[str]

Optional tooltip HTML content (shown on hover).

None
color str

Marker color as hex string.

'#3388ff'
draggable bool

Whether the marker can be dragged.

False
scale float

Marker size multiplier (default 1.0, range 0.1 to 3.0).

1.0
popup_max_width str

Maximum width of popup (CSS value, default "240px").

'240px'
tooltip_max_width str

Maximum width of tooltip (CSS value, default "240px").

'240px'
name Optional[str]

Marker identifier. If None, auto-generated.

None
**kwargs

Additional marker options.

{}

Returns:

Type Description
str

The marker identifier.

Examples:

>>> from anymap_ts import Map
>>> m = Map(center=[-122.4, 37.8], zoom=10)
>>> m.add_marker(-122.4, 37.8, popup="San Francisco", tooltip="Hover me!")
>>> m.add_marker(-122.5, 37.7, scale=1.5, color="#ff0000")
Source code in anymap_ts/maplibre.py
def add_marker(
    self,
    lng: float,
    lat: float,
    popup: Optional[str] = None,
    tooltip: Optional[str] = None,
    color: str = "#3388ff",
    draggable: bool = False,
    scale: float = 1.0,
    popup_max_width: str = "240px",
    tooltip_max_width: str = "240px",
    name: Optional[str] = None,
    **kwargs,
) -> str:
    """Add a single marker to the map.

    Args:
        lng: Longitude of the marker.
        lat: Latitude of the marker.
        popup: Optional popup HTML content (shown on click).
        tooltip: Optional tooltip HTML content (shown on hover).
        color: Marker color as hex string.
        draggable: Whether the marker can be dragged.
        scale: Marker size multiplier (default 1.0, range 0.1 to 3.0).
        popup_max_width: Maximum width of popup (CSS value, default "240px").
        tooltip_max_width: Maximum width of tooltip (CSS value, default "240px").
        name: Marker identifier. If None, auto-generated.
        **kwargs: Additional marker options.

    Returns:
        The marker identifier.

    Example:
        >>> from anymap_ts import Map
        >>> m = Map(center=[-122.4, 37.8], zoom=10)
        >>> m.add_marker(-122.4, 37.8, popup="San Francisco", tooltip="Hover me!")
        >>> m.add_marker(-122.5, 37.7, scale=1.5, color="#ff0000")
    """
    marker_id = name or f"marker-{len(self._layers)}"

    self.call_js_method(
        "addMarker",
        lng,
        lat,
        id=marker_id,
        popup=popup,
        tooltip=tooltip,
        color=color,
        draggable=draggable,
        scale=scale,
        popupMaxWidth=popup_max_width,
        tooltipMaxWidth=tooltip_max_width,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        marker_id: {
            "id": marker_id,
            "type": "marker",
            "lngLat": [lng, lat],
        },
    }
    self._add_to_layer_dict(marker_id, "Markers")
    return marker_id

add_markers(self, data, lng_column=None, lat_column=None, popup_column=None, tooltip_column=None, color='#3388ff', scale=1.0, popup_max_width='240px', tooltip_max_width='240px', draggable=False, name=None, **kwargs)

Add multiple markers from data.

Parameters:

Name Type Description Default
data Any

Data source - can be: - List of dicts with 'lng'/'lon'/'longitude' and 'lat'/'latitude' keys - GeoDataFrame with Point geometries - GeoJSON FeatureCollection with Point features

required
lng_column Optional[str]

Column name for longitude (auto-detected if None).

None
lat_column Optional[str]

Column name for latitude (auto-detected if None).

None
popup_column Optional[str]

Column name for popup content (shown on click).

None
tooltip_column Optional[str]

Column name for tooltip content (shown on hover).

None
color str

Marker color as hex string.

'#3388ff'
scale float

Marker size multiplier (default 1.0, range 0.1 to 3.0).

1.0
popup_max_width str

Maximum width of popup (CSS value, default "240px").

'240px'
tooltip_max_width str

Maximum width of tooltip (CSS value, default "240px").

'240px'
draggable bool

Whether markers can be dragged.

False
name Optional[str]

Layer identifier. If None, auto-generated.

None
**kwargs

Additional marker options.

{}

Returns:

Type Description
str

The layer identifier.

Examples:

>>> from anymap_ts import Map
>>> m = Map()
>>> cities = [
...     {"name": "SF", "info": "San Francisco", "lng": -122.4, "lat": 37.8},
...     {"name": "NYC", "info": "New York City", "lng": -74.0, "lat": 40.7},
... ]
>>> m.add_markers(cities, popup_column="name", tooltip_column="info", scale=1.5)
Source code in anymap_ts/maplibre.py
def add_markers(
    self,
    data: Any,
    lng_column: Optional[str] = None,
    lat_column: Optional[str] = None,
    popup_column: Optional[str] = None,
    tooltip_column: Optional[str] = None,
    color: str = "#3388ff",
    scale: float = 1.0,
    popup_max_width: str = "240px",
    tooltip_max_width: str = "240px",
    draggable: bool = False,
    name: Optional[str] = None,
    **kwargs,
) -> str:
    """Add multiple markers from data.

    Args:
        data: Data source - can be:
            - List of dicts with 'lng'/'lon'/'longitude' and 'lat'/'latitude' keys
            - GeoDataFrame with Point geometries
            - GeoJSON FeatureCollection with Point features
        lng_column: Column name for longitude (auto-detected if None).
        lat_column: Column name for latitude (auto-detected if None).
        popup_column: Column name for popup content (shown on click).
        tooltip_column: Column name for tooltip content (shown on hover).
        color: Marker color as hex string.
        scale: Marker size multiplier (default 1.0, range 0.1 to 3.0).
        popup_max_width: Maximum width of popup (CSS value, default "240px").
        tooltip_max_width: Maximum width of tooltip (CSS value, default "240px").
        draggable: Whether markers can be dragged.
        name: Layer identifier. If None, auto-generated.
        **kwargs: Additional marker options.

    Returns:
        The layer identifier.

    Example:
        >>> from anymap_ts import Map
        >>> m = Map()
        >>> cities = [
        ...     {"name": "SF", "info": "San Francisco", "lng": -122.4, "lat": 37.8},
        ...     {"name": "NYC", "info": "New York City", "lng": -74.0, "lat": 40.7},
        ... ]
        >>> m.add_markers(cities, popup_column="name", tooltip_column="info", scale=1.5)
    """
    layer_id = name or f"markers-{len(self._layers)}"
    markers = []

    # Handle GeoDataFrame
    if hasattr(data, "geometry"):
        for _, row in data.iterrows():
            geom = row.geometry
            if geom.geom_type == "Point":
                marker = {"lngLat": [geom.x, geom.y]}
                if popup_column and popup_column in row:
                    marker["popup"] = str(row[popup_column])
                if tooltip_column and tooltip_column in row:
                    marker["tooltip"] = str(row[tooltip_column])
                markers.append(marker)
    # Handle GeoJSON
    elif isinstance(data, dict) and data.get("type") == "FeatureCollection":
        for feature in data.get("features", []):
            geom = feature.get("geometry", {})
            if geom.get("type") == "Point":
                coords = geom.get("coordinates", [])
                marker = {"lngLat": coords[:2]}
                props = feature.get("properties", {})
                if popup_column and popup_column in props:
                    marker["popup"] = str(props[popup_column])
                if tooltip_column and tooltip_column in props:
                    marker["tooltip"] = str(props[tooltip_column])
                markers.append(marker)
    # Handle list of dicts
    elif isinstance(data, list):
        lng_keys = ["lng", "lon", "longitude", "x"]
        lat_keys = ["lat", "latitude", "y"]

        for item in data:
            if not isinstance(item, dict):
                continue

            # Find lng/lat values
            lng_val = None
            lat_val = None

            if lng_column and lng_column in item:
                lng_val = item[lng_column]
            else:
                for key in lng_keys:
                    if key in item:
                        lng_val = item[key]
                        break

            if lat_column and lat_column in item:
                lat_val = item[lat_column]
            else:
                for key in lat_keys:
                    if key in item:
                        lat_val = item[key]
                        break

            if lng_val is not None and lat_val is not None:
                marker = {"lngLat": [float(lng_val), float(lat_val)]}
                if popup_column and popup_column in item:
                    marker["popup"] = str(item[popup_column])
                if tooltip_column and tooltip_column in item:
                    marker["tooltip"] = str(item[tooltip_column])
                markers.append(marker)

    if not markers:
        raise ValueError("No valid point data found in input")

    self.call_js_method(
        "addMarkers",
        id=layer_id,
        markers=markers,
        color=color,
        scale=scale,
        popupMaxWidth=popup_max_width,
        tooltipMaxWidth=tooltip_max_width,
        draggable=draggable,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "markers",
            "count": len(markers),
        },
    }
    self._add_to_layer_dict(layer_id, "Markers")
    return layer_id

add_measure_control(self, position='top-right', collapsed=True, default_mode='distance', distance_unit='kilometers', area_unit='square-kilometers', line_color='#3b82f6', fill_color='rgba(59, 130, 246, 0.2)', **kwargs)

Add a measurement control for distances and areas.

Provides tools for measuring distances (polylines) and areas (polygons) interactively on the map.

Parameters:

Name Type Description Default
position str

Control position ('top-left', 'top-right', 'bottom-left', 'bottom-right').

'top-right'
collapsed bool

Whether the control starts collapsed.

True
default_mode str

Default measurement mode ('distance' or 'area').

'distance'
distance_unit str

Distance unit ('kilometers', 'miles', 'meters', 'feet', 'nautical-miles').

'kilometers'
area_unit str

Area unit ('square-kilometers', 'square-miles', 'square-meters', 'hectares', 'acres').

'square-kilometers'
line_color str

Line color for distance measurements.

'#3b82f6'
fill_color str

Fill color for area measurements.

'rgba(59, 130, 246, 0.2)'
**kwargs

Additional MeasureControl options.

{}

Examples:

>>> m = Map()
>>> m.add_measure_control(
...     default_mode="distance",
...     distance_unit="miles",
... )
Source code in anymap_ts/maplibre.py
def add_measure_control(
    self,
    position: str = "top-right",
    collapsed: bool = True,
    default_mode: str = "distance",
    distance_unit: str = "kilometers",
    area_unit: str = "square-kilometers",
    line_color: str = "#3b82f6",
    fill_color: str = "rgba(59, 130, 246, 0.2)",
    **kwargs,
) -> None:
    """Add a measurement control for distances and areas.

    Provides tools for measuring distances (polylines) and areas
    (polygons) interactively on the map.

    Args:
        position: Control position ('top-left', 'top-right',
            'bottom-left', 'bottom-right').
        collapsed: Whether the control starts collapsed.
        default_mode: Default measurement mode ('distance' or 'area').
        distance_unit: Distance unit ('kilometers', 'miles', 'meters',
            'feet', 'nautical-miles').
        area_unit: Area unit ('square-kilometers', 'square-miles',
            'square-meters', 'hectares', 'acres').
        line_color: Line color for distance measurements.
        fill_color: Fill color for area measurements.
        **kwargs: Additional MeasureControl options.

    Example:
        >>> m = Map()
        >>> m.add_measure_control(
        ...     default_mode="distance",
        ...     distance_unit="miles",
        ... )
    """
    self._validate_position(position)
    self.call_js_method(
        "addMeasureControl",
        position=position,
        collapsed=collapsed,
        defaultMode=default_mode,
        distanceUnit=distance_unit,
        areaUnit=area_unit,
        lineColor=line_color,
        fillColor=fill_color,
        **kwargs,
    )
    self._controls = {
        **self._controls,
        "measure-control": {
            "type": "measure-control",
            "position": position,
            "collapsed": collapsed,
        },
    }

add_opacity_slider(self, layer_id, position='top-right', label=None)

Add a UI slider to control layer opacity.

Parameters:

Name Type Description Default
layer_id str

Layer ID to control opacity for.

required
position str

Control position.

'top-right'
label Optional[str]

Label text. Defaults to layer_id.

None

Examples:

>>> m = MapLibreMap()
>>> m.add_tile_layer("...", name="satellite")
>>> m.add_opacity_slider("satellite")
Source code in anymap_ts/maplibre.py
def add_opacity_slider(
    self,
    layer_id: str,
    position: str = "top-right",
    label: Optional[str] = None,
) -> None:
    """Add a UI slider to control layer opacity.

    Args:
        layer_id: Layer ID to control opacity for.
        position: Control position.
        label: Label text. Defaults to layer_id.

    Example:
        >>> m = MapLibreMap()
        >>> m.add_tile_layer("...", name="satellite")
        >>> m.add_opacity_slider("satellite")
    """
    self.call_js_method(
        "addOpacitySlider",
        layerId=layer_id,
        position=position,
        label=label or layer_id,
    )

add_path_layer(self, data, name=None, get_path='path', get_color=None, get_width=1, width_scale=1, width_min_pixels=1, pickable=True, opacity=0.8, **kwargs)

Add a path layer for route/trajectory rendering using deck.gl.

Path layers render polylines defined by arrays of coordinates, ideal for visualizing routes, trajectories, or any line-based data.

Parameters:

Name Type Description Default
data Any

Array of data objects with path coordinates.

required
name Optional[str]

Layer ID. If None, auto-generated.

None
get_path Union[str, Any]

Accessor for path coordinates [[lng, lat], ...]. Can be a string (property name) or a value.

'path'
get_color Optional[Union[List[int], str]]

Accessor for path color [r, g, b, a]. Default: [51, 136, 255, 200] (blue).

None
get_width Union[float, str]

Accessor for path width in meters.

1
width_scale float

Global width multiplier.

1
width_min_pixels float

Minimum width in pixels.

1
pickable bool

Whether layer responds to hover/click events.

True
opacity float

Layer opacity (0-1).

0.8
**kwargs

Additional PathLayer props.

{}

Examples:

>>> from anymap_ts import MapLibreMap
>>> m = MapLibreMap()
>>> routes = [
...     {"path": [[-122.4, 37.8], [-122.5, 37.7], [-122.6, 37.8]]},
... ]
>>> m.add_path_layer(routes, get_color=[255, 0, 0], get_width=3)
Source code in anymap_ts/maplibre.py
def add_path_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_path: Union[str, Any] = "path",
    get_color: Optional[Union[List[int], str]] = None,
    get_width: Union[float, str] = 1,
    width_scale: float = 1,
    width_min_pixels: float = 1,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add a path layer for route/trajectory rendering using deck.gl.

    Path layers render polylines defined by arrays of coordinates,
    ideal for visualizing routes, trajectories, or any line-based data.

    Args:
        data: Array of data objects with path coordinates.
        name: Layer ID. If None, auto-generated.
        get_path: Accessor for path coordinates [[lng, lat], ...].
            Can be a string (property name) or a value.
        get_color: Accessor for path color [r, g, b, a].
            Default: [51, 136, 255, 200] (blue).
        get_width: Accessor for path width in meters.
        width_scale: Global width multiplier.
        width_min_pixels: Minimum width in pixels.
        pickable: Whether layer responds to hover/click events.
        opacity: Layer opacity (0-1).
        **kwargs: Additional PathLayer props.

    Example:
        >>> from anymap_ts import MapLibreMap
        >>> m = MapLibreMap()
        >>> routes = [
        ...     {"path": [[-122.4, 37.8], [-122.5, 37.7], [-122.6, 37.8]]},
        ... ]
        >>> m.add_path_layer(routes, get_color=[255, 0, 0], get_width=3)
    """
    layer_id = name or f"path-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addPathLayer",
        id=layer_id,
        data=processed_data,
        getPath=get_path,
        getColor=get_color or [51, 136, 255, 200],
        getWidth=get_width,
        widthScale=width_scale,
        widthMinPixels=width_min_pixels,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "path",
        },
    }
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_pmtiles_control(self, position='top-right', collapsed=True, default_url=None, load_default_url=False, default_opacity=1.0, default_fill_color='steelblue', default_line_color='#333', default_pickable=True, **kwargs)

Add a PMTiles layer control for loading PMTiles files via UI.

This provides an interactive panel for users to enter PMTiles URLs and visualize vector or raster tile data.

Parameters:

Name Type Description Default
position str

Control position ('top-left', 'top-right', 'bottom-left', 'bottom-right').

'top-right'
collapsed bool

Whether the panel starts collapsed.

True
default_url Optional[str]

Default PMTiles URL to pre-fill.

None
load_default_url bool

Whether to auto-load the default URL.

False
default_opacity float

Default layer opacity (0-1).

1.0
default_fill_color str

Default fill color for vector polygons.

'steelblue'
default_line_color str

Default line color for vector lines.

'#333'
default_pickable bool

Whether features are clickable by default.

True
**kwargs

Additional control options.

{}

Examples:

>>> from anymap_ts import MapLibreMap
>>> m = MapLibreMap()
>>> m.add_pmtiles_control(
...     default_url="https://pmtiles.io/protomaps(vector)ODbL_firenze.pmtiles",
...     load_default_url=True
... )
Source code in anymap_ts/maplibre.py
def add_pmtiles_control(
    self,
    position: str = "top-right",
    collapsed: bool = True,
    default_url: Optional[str] = None,
    load_default_url: bool = False,
    default_opacity: float = 1.0,
    default_fill_color: str = "steelblue",
    default_line_color: str = "#333",
    default_pickable: bool = True,
    **kwargs,
) -> None:
    """Add a PMTiles layer control for loading PMTiles files via UI.

    This provides an interactive panel for users to enter PMTiles URLs
    and visualize vector or raster tile data.

    Args:
        position: Control position ('top-left', 'top-right', 'bottom-left', 'bottom-right').
        collapsed: Whether the panel starts collapsed.
        default_url: Default PMTiles URL to pre-fill.
        load_default_url: Whether to auto-load the default URL.
        default_opacity: Default layer opacity (0-1).
        default_fill_color: Default fill color for vector polygons.
        default_line_color: Default line color for vector lines.
        default_pickable: Whether features are clickable by default.
        **kwargs: Additional control options.

    Example:
        >>> from anymap_ts import MapLibreMap
        >>> m = MapLibreMap()
        >>> m.add_pmtiles_control(
        ...     default_url="https://pmtiles.io/protomaps(vector)ODbL_firenze.pmtiles",
        ...     load_default_url=True
        ... )
    """
    self.call_js_method(
        "addPMTilesControl",
        position=position,
        collapsed=collapsed,
        defaultUrl=default_url or "",
        loadDefaultUrl=load_default_url,
        defaultOpacity=default_opacity,
        defaultFillColor=default_fill_color,
        defaultLineColor=default_line_color,
        defaultPickable=default_pickable,
        **kwargs,
    )
    self._controls = {
        **self._controls,
        "pmtiles-control": {"position": position, "collapsed": collapsed},
    }

add_pmtiles_layer(self, url, layer_id=None, style=None, opacity=1.0, visible=True, fit_bounds=False, source_type='vector', **kwargs)

Add a PMTiles layer for efficient vector or raster tile serving.

PMTiles is a single-file archive format for pyramids of map tiles. It enables efficient web-native map serving without requiring a separate tile server infrastructure.

Parameters:

Name Type Description Default
url str

URL to the PMTiles file (e.g., "https://example.com/data.pmtiles").

required
layer_id Optional[str]

Layer identifier. If None, auto-generated.

None
style Optional[Dict[str, Any]]

Layer style configuration for vector tiles. For vector PMTiles, can include: - type: Layer type ('fill', 'line', 'circle', 'symbol') - source-layer: Source layer name from vector tiles - paint properties (e.g., 'fill-color', 'line-width') - layout properties (e.g., 'visibility') Example: {"type": "line", "source-layer": "roads", "line-color": "#ff0000"}

None
opacity float

Layer opacity (0-1).

1.0
visible bool

Whether layer is initially visible.

True
fit_bounds bool

Whether to fit map to layer bounds after loading.

False
source_type str

Source type - "vector" for vector PMTiles, "raster" for raster PMTiles.

'vector'
**kwargs

Additional layer options.

{}

Examples:

>>> from anymap_ts import Map
>>> m = Map()
>>> # Add vector PMTiles
>>> m.add_pmtiles_layer(
...     url="https://example.com/countries.pmtiles",
...     layer_id="countries",
...     style={
...         "type": "fill",
...         "source-layer": "countries",
...         "fill-color": "#3388ff",
...         "fill-opacity": 0.6
...     }
... )
>>> # Add raster PMTiles
>>> m.add_pmtiles_layer(
...     url="https://example.com/satellite.pmtiles",
...     layer_id="satellite",
...     source_type="raster",
...     opacity=0.8
... )
Source code in anymap_ts/maplibre.py
def add_pmtiles_layer(
    self,
    url: str,
    layer_id: Optional[str] = None,
    style: Optional[Dict[str, Any]] = None,
    opacity: float = 1.0,
    visible: bool = True,
    fit_bounds: bool = False,
    source_type: str = "vector",
    **kwargs,
) -> None:
    """Add a PMTiles layer for efficient vector or raster tile serving.

    PMTiles is a single-file archive format for pyramids of map tiles.
    It enables efficient web-native map serving without requiring a
    separate tile server infrastructure.

    Args:
        url: URL to the PMTiles file (e.g., "https://example.com/data.pmtiles").
        layer_id: Layer identifier. If None, auto-generated.
        style: Layer style configuration for vector tiles.
            For vector PMTiles, can include:
            - type: Layer type ('fill', 'line', 'circle', 'symbol')
            - source-layer: Source layer name from vector tiles
            - paint properties (e.g., 'fill-color', 'line-width')
            - layout properties (e.g., 'visibility')
            Example: {"type": "line", "source-layer": "roads", "line-color": "#ff0000"}
        opacity: Layer opacity (0-1).
        visible: Whether layer is initially visible.
        fit_bounds: Whether to fit map to layer bounds after loading.
        source_type: Source type - "vector" for vector PMTiles, "raster" for raster PMTiles.
        **kwargs: Additional layer options.

    Example:
        >>> from anymap_ts import Map
        >>> m = Map()
        >>> # Add vector PMTiles
        >>> m.add_pmtiles_layer(
        ...     url="https://example.com/countries.pmtiles",
        ...     layer_id="countries",
        ...     style={
        ...         "type": "fill",
        ...         "source-layer": "countries",
        ...         "fill-color": "#3388ff",
        ...         "fill-opacity": 0.6
        ...     }
        ... )
        >>> # Add raster PMTiles
        >>> m.add_pmtiles_layer(
        ...     url="https://example.com/satellite.pmtiles",
        ...     layer_id="satellite",
        ...     source_type="raster",
        ...     opacity=0.8
        ... )
    """
    layer_id = layer_id or f"pmtiles-{len(self._layers)}"

    self.call_js_method(
        "addPMTilesLayer",
        url=url,
        id=layer_id,
        style=style or {},
        opacity=opacity,
        visible=visible,
        fitBounds=fit_bounds,
        sourceType=source_type,
        name=layer_id,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "pmtiles",
            "url": url,
            "source_type": source_type,
        },
    }
    category = "Vector" if source_type == "vector" else "Raster"
    self._add_to_layer_dict(layer_id, category)

add_point_cloud_layer(self, data, name=None, get_position='position', get_color=None, get_normal=None, point_size=2, size_units='pixels', pickable=True, opacity=1.0, material=True, coordinate_system=None, coordinate_origin=None, **kwargs)

Add a point cloud layer for 3D point visualization using deck.gl.

Point cloud layers render large collections of 3D points, ideal for LiDAR data, photogrammetry outputs, or any 3D point dataset.

Parameters:

Name Type Description Default
data Any

Array of point data with positions. Each point should have x, y, z coordinates (or position array).

required
name Optional[str]

Layer ID. If None, auto-generated.

None
get_position Union[str, Any]

Accessor for point position [x, y, z]. Can be a string (property name) or a value.

'position'
get_color Optional[Union[List[int], str]]

Accessor or value for point color [r, g, b, a]. Default: [255, 255, 255, 255] (white).

None
get_normal Optional[Union[str, Any]]

Accessor for point normal [nx, ny, nz] for lighting. Default: [0, 0, 1] (pointing up).

None
point_size float

Point size in pixels or meters (depends on size_units).

2
size_units str

Size units: 'pixels', 'meters', or 'common'.

'pixels'
pickable bool

Whether layer responds to hover/click events.

True
opacity float

Layer opacity (0-1).

1.0
material bool

Whether to enable lighting effects.

True
coordinate_system Optional[int]

Coordinate system for positions.

None
coordinate_origin Optional[List[float]]

Origin for coordinate system [x, y, z].

None
**kwargs

Additional PointCloudLayer props.

{}

Examples:

>>> from anymap_ts import MapLibreMap
>>> import numpy as np
>>> m = MapLibreMap(pitch=45)
>>> points = [
...     {"position": [-122.4, 37.8, 100], "color": [255, 0, 0, 255]},
...     {"position": [-122.3, 37.7, 200], "color": [0, 255, 0, 255]},
... ]
>>> m.add_point_cloud_layer(points, point_size=5)
Source code in anymap_ts/maplibre.py
def add_point_cloud_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_position: Union[str, Any] = "position",
    get_color: Optional[Union[List[int], str]] = None,
    get_normal: Optional[Union[str, Any]] = None,
    point_size: float = 2,
    size_units: str = "pixels",
    pickable: bool = True,
    opacity: float = 1.0,
    material: bool = True,
    coordinate_system: Optional[int] = None,
    coordinate_origin: Optional[List[float]] = None,
    **kwargs,
) -> None:
    """Add a point cloud layer for 3D point visualization using deck.gl.

    Point cloud layers render large collections of 3D points, ideal for
    LiDAR data, photogrammetry outputs, or any 3D point dataset.

    Args:
        data: Array of point data with positions. Each point should have
            x, y, z coordinates (or position array).
        name: Layer ID. If None, auto-generated.
        get_position: Accessor for point position [x, y, z].
            Can be a string (property name) or a value.
        get_color: Accessor or value for point color [r, g, b, a].
            Default: [255, 255, 255, 255] (white).
        get_normal: Accessor for point normal [nx, ny, nz] for lighting.
            Default: [0, 0, 1] (pointing up).
        point_size: Point size in pixels or meters (depends on size_units).
        size_units: Size units: 'pixels', 'meters', or 'common'.
        pickable: Whether layer responds to hover/click events.
        opacity: Layer opacity (0-1).
        material: Whether to enable lighting effects.
        coordinate_system: Coordinate system for positions.
        coordinate_origin: Origin for coordinate system [x, y, z].
        **kwargs: Additional PointCloudLayer props.

    Example:
        >>> from anymap_ts import MapLibreMap
        >>> import numpy as np
        >>> m = MapLibreMap(pitch=45)
        >>> points = [
        ...     {"position": [-122.4, 37.8, 100], "color": [255, 0, 0, 255]},
        ...     {"position": [-122.3, 37.7, 200], "color": [0, 255, 0, 255]},
        ... ]
        >>> m.add_point_cloud_layer(points, point_size=5)
    """
    layer_id = name or f"pointcloud-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addPointCloudLayer",
        id=layer_id,
        data=processed_data,
        getPosition=get_position,
        getColor=get_color or [255, 255, 255, 255],
        getNormal=get_normal,
        pointSize=point_size,
        sizeUnits=size_units,
        pickable=pickable,
        opacity=opacity,
        material=material,
        coordinateSystem=coordinate_system,
        coordinateOrigin=coordinate_origin,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "pointcloud",
        },
    }
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_polygon_layer(self, data, name=None, get_polygon='polygon', get_fill_color=None, get_line_color=None, get_line_width=1, get_elevation=0, extruded=False, wireframe=False, filled=True, stroked=True, line_width_min_pixels=1, pickable=True, opacity=0.5, **kwargs)

Add a polygon layer for filled polygon visualization using deck.gl.

Polygon layers render filled and/or stroked polygons with optional 3D extrusion, ideal for choropleth maps and area visualizations.

Parameters:

Name Type Description Default
data Any

Array of data objects with polygon coordinates.

required
name Optional[str]

Layer ID. If None, auto-generated.

None
get_polygon Union[str, Any]

Accessor for polygon coordinates. Can be a string (property name) or a value.

'polygon'
get_fill_color Optional[Union[List[int], str]]

Accessor for fill color [r, g, b, a]. Default: [51, 136, 255, 128].

None
get_line_color Optional[Union[List[int], str]]

Accessor for stroke color [r, g, b, a]. Default: [0, 0, 255, 255].

None
get_line_width Union[float, str]

Accessor for stroke width.

1
get_elevation Union[float, str]

Accessor for 3D extrusion height.

0
extruded bool

Whether to render as 3D polygons.

False
wireframe bool

Whether to render wireframe (extruded only).

False
filled bool

Whether to fill polygons.

True
stroked bool

Whether to draw stroke.

True
line_width_min_pixels float

Minimum stroke width in pixels.

1
pickable bool

Whether layer responds to hover/click events.

True
opacity float

Layer opacity (0-1).

0.5
**kwargs

Additional PolygonLayer props.

{}

Examples:

>>> from anymap_ts import MapLibreMap
>>> m = MapLibreMap(pitch=45)
>>> polygons = [
...     {"polygon": [[-122.4, 37.8], [-122.5, 37.7], [-122.3, 37.7]], "height": 1000},
... ]
>>> m.add_polygon_layer(polygons, extruded=True, get_elevation="height")
Source code in anymap_ts/maplibre.py
def add_polygon_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_polygon: Union[str, Any] = "polygon",
    get_fill_color: Optional[Union[List[int], str]] = None,
    get_line_color: Optional[Union[List[int], str]] = None,
    get_line_width: Union[float, str] = 1,
    get_elevation: Union[float, str] = 0,
    extruded: bool = False,
    wireframe: bool = False,
    filled: bool = True,
    stroked: bool = True,
    line_width_min_pixels: float = 1,
    pickable: bool = True,
    opacity: float = 0.5,
    **kwargs,
) -> None:
    """Add a polygon layer for filled polygon visualization using deck.gl.

    Polygon layers render filled and/or stroked polygons with optional
    3D extrusion, ideal for choropleth maps and area visualizations.

    Args:
        data: Array of data objects with polygon coordinates.
        name: Layer ID. If None, auto-generated.
        get_polygon: Accessor for polygon coordinates.
            Can be a string (property name) or a value.
        get_fill_color: Accessor for fill color [r, g, b, a].
            Default: [51, 136, 255, 128].
        get_line_color: Accessor for stroke color [r, g, b, a].
            Default: [0, 0, 255, 255].
        get_line_width: Accessor for stroke width.
        get_elevation: Accessor for 3D extrusion height.
        extruded: Whether to render as 3D polygons.
        wireframe: Whether to render wireframe (extruded only).
        filled: Whether to fill polygons.
        stroked: Whether to draw stroke.
        line_width_min_pixels: Minimum stroke width in pixels.
        pickable: Whether layer responds to hover/click events.
        opacity: Layer opacity (0-1).
        **kwargs: Additional PolygonLayer props.

    Example:
        >>> from anymap_ts import MapLibreMap
        >>> m = MapLibreMap(pitch=45)
        >>> polygons = [
        ...     {"polygon": [[-122.4, 37.8], [-122.5, 37.7], [-122.3, 37.7]], "height": 1000},
        ... ]
        >>> m.add_polygon_layer(polygons, extruded=True, get_elevation="height")
    """
    layer_id = name or f"polygon-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addPolygonLayer",
        id=layer_id,
        data=processed_data,
        getPolygon=get_polygon,
        getFillColor=get_fill_color or [51, 136, 255, 128],
        getLineColor=get_line_color or [0, 0, 255, 255],
        getLineWidth=get_line_width,
        getElevation=get_elevation,
        extruded=extruded,
        wireframe=wireframe,
        filled=filled,
        stroked=stroked,
        lineWidthMinPixels=line_width_min_pixels,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "polygon",
        },
    }
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_popup(self, layer_id, properties=None, template=None, **kwargs)

Add popup on click for a layer.

Configures a layer to show a popup when features are clicked.

Parameters:

Name Type Description Default
layer_id str

Layer identifier to add popup to.

required
properties Optional[List[str]]

List of property names to display. If None, shows all.

None
template Optional[str]

Custom HTML template for popup content. Use {property_name} placeholders for values. If None, auto-generates table.

None
**kwargs

Additional popup options (maxWidth, closeButton, etc.).

{}

Examples:

>>> m.add_vector(geojson, name="cities")
>>> m.add_popup("cities", properties=["name", "population"])
>>> # Or with custom template:
>>> m.add_popup("cities", template="<h3>{name}</h3><p>Pop: {population}</p>")
Source code in anymap_ts/maplibre.py
def add_popup(
    self,
    layer_id: str,
    properties: Optional[List[str]] = None,
    template: Optional[str] = None,
    **kwargs,
) -> None:
    """Add popup on click for a layer.

    Configures a layer to show a popup when features are clicked.

    Args:
        layer_id: Layer identifier to add popup to.
        properties: List of property names to display. If None, shows all.
        template: Custom HTML template for popup content. Use {property_name}
            placeholders for values. If None, auto-generates table.
        **kwargs: Additional popup options (maxWidth, closeButton, etc.).

    Example:
        >>> m.add_vector(geojson, name="cities")
        >>> m.add_popup("cities", properties=["name", "population"])
        >>> # Or with custom template:
        >>> m.add_popup("cities", template="<h3>{name}</h3><p>Pop: {population}</p>")
    """
    self.call_js_method(
        "addPopup",
        layerId=layer_id,
        properties=properties,
        template=template,
        **kwargs,
    )

add_print_control(self, position='top-right', collapsed=True, format='png', filename='map-export', include_north_arrow=False, include_scale_bar=False, **kwargs)

Add a print/export control for saving the map as an image.

Provides an interactive panel for exporting the current map view as PNG, JPEG, or PDF files.

Parameters:

Name Type Description Default
position str

Control position ('top-left', 'top-right', 'bottom-left', 'bottom-right').

'top-right'
collapsed bool

Whether the control starts collapsed.

True
format str

Default image format ('png', 'jpeg', 'pdf').

'png'
filename str

Default filename (without extension).

'map-export'
include_north_arrow bool

Whether to include a north arrow by default.

False
include_scale_bar bool

Whether to include a scale bar by default.

False
**kwargs

Additional PrintControl options.

{}

Examples:

>>> m = Map()
>>> m.add_print_control(
...     format="png",
...     filename="my-map",
...     include_scale_bar=True,
... )
Source code in anymap_ts/maplibre.py
def add_print_control(
    self,
    position: str = "top-right",
    collapsed: bool = True,
    format: str = "png",
    filename: str = "map-export",
    include_north_arrow: bool = False,
    include_scale_bar: bool = False,
    **kwargs,
) -> None:
    """Add a print/export control for saving the map as an image.

    Provides an interactive panel for exporting the current map view
    as PNG, JPEG, or PDF files.

    Args:
        position: Control position ('top-left', 'top-right',
            'bottom-left', 'bottom-right').
        collapsed: Whether the control starts collapsed.
        format: Default image format ('png', 'jpeg', 'pdf').
        filename: Default filename (without extension).
        include_north_arrow: Whether to include a north arrow by default.
        include_scale_bar: Whether to include a scale bar by default.
        **kwargs: Additional PrintControl options.

    Example:
        >>> m = Map()
        >>> m.add_print_control(
        ...     format="png",
        ...     filename="my-map",
        ...     include_scale_bar=True,
        ... )
    """
    self._validate_position(position)
    self.call_js_method(
        "addPrintControl",
        position=position,
        collapsed=collapsed,
        format=format,
        filename=filename,
        includeNorthArrow=include_north_arrow,
        includeScaleBar=include_scale_bar,
        **kwargs,
    )
    self._controls = {
        **self._controls,
        "print-control": {
            "type": "print-control",
            "position": position,
            "collapsed": collapsed,
        },
    }

add_raster(self, source, name=None, attribution='', indexes=None, colormap=None, vmin=None, vmax=None, nodata=None, fit_bounds=True, **kwargs)

Add a raster layer from a local file using localtileserver.

Parameters:

Name Type Description Default
source str

Path to local raster file

required
name Optional[str]

Layer name

None
attribution str

Attribution text

''
indexes Optional[List[int]]

Band indexes to use

None
colormap Optional[str]

Colormap name

None
vmin Optional[float]

Minimum value for colormap

None
vmax Optional[float]

Maximum value for colormap

None
nodata Optional[float]

NoData value

None
fit_bounds bool

Whether to fit map to raster bounds

True
**kwargs

Additional options

{}
Source code in anymap_ts/maplibre.py
def add_raster(
    self,
    source: str,
    name: Optional[str] = None,
    attribution: str = "",
    indexes: Optional[List[int]] = None,
    colormap: Optional[str] = None,
    vmin: Optional[float] = None,
    vmax: Optional[float] = None,
    nodata: Optional[float] = None,
    fit_bounds: bool = True,
    **kwargs,
) -> None:
    """Add a raster layer from a local file using localtileserver.

    Args:
        source: Path to local raster file
        name: Layer name
        attribution: Attribution text
        indexes: Band indexes to use
        colormap: Colormap name
        vmin: Minimum value for colormap
        vmax: Maximum value for colormap
        nodata: NoData value
        fit_bounds: Whether to fit map to raster bounds
        **kwargs: Additional options
    """
    try:
        from localtileserver import TileClient
    except ImportError:
        raise ImportError(
            "localtileserver is required for local raster support. "
            "Install with: pip install anymap-ts[raster]"
        )

    client = TileClient(source)

    # Build parameters dict and pass all at once
    tile_params = {}
    if indexes:
        tile_params["indexes"] = indexes
    if colormap:
        tile_params["colormap"] = colormap
    if vmin is not None or vmax is not None:
        tile_params["vmin"] = vmin if vmin is not None else client.min
        tile_params["vmax"] = vmax if vmax is not None else client.max
    if nodata is not None:
        tile_params["nodata"] = nodata

    tile_url = client.get_tile_url(**tile_params)

    layer_name = name or Path(source).stem

    self.add_tile_layer(
        tile_url,
        name=layer_name,
        attribution=attribution,
        **kwargs,
    )

    # Fit bounds if requested
    if fit_bounds:
        bounds = client.bounds()
        if bounds:
            self.fit_bounds([bounds[0], bounds[1], bounds[2], bounds[3]])

add_scatterplot_layer(self, data, name=None, get_position='coordinates', get_radius=5, get_fill_color=None, get_line_color=None, radius_scale=1, radius_min_pixels=1, radius_max_pixels=100, line_width_min_pixels=1, stroked=True, filled=True, pickable=True, opacity=0.8, **kwargs)

Add a scatterplot layer for sized/colored point visualization using deck.gl.

Scatterplot layers render circles at given coordinates with configurable radius and color, ideal for point datasets where size and color encode data.

Parameters:

Name Type Description Default
data Any

Array of data objects or GeoJSON with point coordinates.

required
name Optional[str]

Layer ID. If None, auto-generated.

None
get_position Union[str, Any]

Accessor for point position [lng, lat]. Can be a string (property name) or a value.

'coordinates'
get_radius Union[float, str]

Accessor for point radius in meters.

5
get_fill_color Optional[Union[List[int], str]]

Accessor for fill color [r, g, b, a]. Default: [51, 136, 255, 200] (blue).

None
get_line_color Optional[Union[List[int], str]]

Accessor for stroke color [r, g, b, a]. Default: [255, 255, 255, 255] (white).

None
radius_scale float

Global radius multiplier.

1
radius_min_pixels float

Minimum radius in pixels.

1
radius_max_pixels float

Maximum radius in pixels.

100
line_width_min_pixels float

Minimum stroke width in pixels.

1
stroked bool

Whether to draw stroke around points.

True
filled bool

Whether to fill points.

True
pickable bool

Whether layer responds to hover/click events.

True
opacity float

Layer opacity (0-1).

0.8
**kwargs

Additional ScatterplotLayer props.

{}

Examples:

>>> from anymap_ts import MapLibreMap
>>> m = MapLibreMap()
>>> points = [
...     {"coordinates": [-122.4, 37.8], "size": 100},
...     {"coordinates": [-122.5, 37.7], "size": 200},
... ]
>>> m.add_scatterplot_layer(points, get_radius="size")
Source code in anymap_ts/maplibre.py
def add_scatterplot_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_position: Union[str, Any] = "coordinates",
    get_radius: Union[float, str] = 5,
    get_fill_color: Optional[Union[List[int], str]] = None,
    get_line_color: Optional[Union[List[int], str]] = None,
    radius_scale: float = 1,
    radius_min_pixels: float = 1,
    radius_max_pixels: float = 100,
    line_width_min_pixels: float = 1,
    stroked: bool = True,
    filled: bool = True,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add a scatterplot layer for sized/colored point visualization using deck.gl.

    Scatterplot layers render circles at given coordinates with configurable
    radius and color, ideal for point datasets where size and color encode data.

    Args:
        data: Array of data objects or GeoJSON with point coordinates.
        name: Layer ID. If None, auto-generated.
        get_position: Accessor for point position [lng, lat].
            Can be a string (property name) or a value.
        get_radius: Accessor for point radius in meters.
        get_fill_color: Accessor for fill color [r, g, b, a].
            Default: [51, 136, 255, 200] (blue).
        get_line_color: Accessor for stroke color [r, g, b, a].
            Default: [255, 255, 255, 255] (white).
        radius_scale: Global radius multiplier.
        radius_min_pixels: Minimum radius in pixels.
        radius_max_pixels: Maximum radius in pixels.
        line_width_min_pixels: Minimum stroke width in pixels.
        stroked: Whether to draw stroke around points.
        filled: Whether to fill points.
        pickable: Whether layer responds to hover/click events.
        opacity: Layer opacity (0-1).
        **kwargs: Additional ScatterplotLayer props.

    Example:
        >>> from anymap_ts import MapLibreMap
        >>> m = MapLibreMap()
        >>> points = [
        ...     {"coordinates": [-122.4, 37.8], "size": 100},
        ...     {"coordinates": [-122.5, 37.7], "size": 200},
        ... ]
        >>> m.add_scatterplot_layer(points, get_radius="size")
    """
    layer_id = name or f"scatterplot-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addScatterplotLayer",
        id=layer_id,
        data=processed_data,
        getPosition=get_position,
        getRadius=get_radius,
        getFillColor=get_fill_color or [51, 136, 255, 200],
        getLineColor=get_line_color or [255, 255, 255, 255],
        radiusScale=radius_scale,
        radiusMinPixels=radius_min_pixels,
        radiusMaxPixels=radius_max_pixels,
        lineWidthMinPixels=line_width_min_pixels,
        stroked=stroked,
        filled=filled,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "scatterplot",
        },
    }
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_screen_grid_layer(self, data, name=None, get_position='coordinates', get_weight=1, cell_size_pixels=50, color_range=None, pickable=True, opacity=0.8, **kwargs)

Add a screen grid layer for screen-space grid aggregation using deck.gl.

Screen grid layers aggregate points into a grid in screen space, providing a fast overview of point density that updates on zoom/pan.

Parameters:

Name Type Description Default
data Any

Array of data objects with position coordinates.

required
name Optional[str]

Layer ID. If None, auto-generated.

None
get_position Union[str, Any]

Accessor for point position [lng, lat].

'coordinates'
get_weight Union[float, str]

Accessor for point weight value.

1
cell_size_pixels float

Grid cell size in screen pixels.

50
color_range Optional[List[List[int]]]

Color gradient [[r, g, b, a], ...].

None
pickable bool

Whether layer responds to hover/click events.

True
opacity float

Layer opacity (0-1).

0.8
**kwargs

Additional ScreenGridLayer props.

{}

Examples:

>>> from anymap_ts import MapLibreMap
>>> m = MapLibreMap()
>>> points = [
...     {"coordinates": [-122.4, 37.8]},
...     {"coordinates": [-122.41, 37.81]},
... ]
>>> m.add_screen_grid_layer(points, cell_size_pixels=30)
Source code in anymap_ts/maplibre.py
def add_screen_grid_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_position: Union[str, Any] = "coordinates",
    get_weight: Union[float, str] = 1,
    cell_size_pixels: float = 50,
    color_range: Optional[List[List[int]]] = None,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add a screen grid layer for screen-space grid aggregation using deck.gl.

    Screen grid layers aggregate points into a grid in screen space,
    providing a fast overview of point density that updates on zoom/pan.

    Args:
        data: Array of data objects with position coordinates.
        name: Layer ID. If None, auto-generated.
        get_position: Accessor for point position [lng, lat].
        get_weight: Accessor for point weight value.
        cell_size_pixels: Grid cell size in screen pixels.
        color_range: Color gradient [[r, g, b, a], ...].
        pickable: Whether layer responds to hover/click events.
        opacity: Layer opacity (0-1).
        **kwargs: Additional ScreenGridLayer props.

    Example:
        >>> from anymap_ts import MapLibreMap
        >>> m = MapLibreMap()
        >>> points = [
        ...     {"coordinates": [-122.4, 37.8]},
        ...     {"coordinates": [-122.41, 37.81]},
        ... ]
        >>> m.add_screen_grid_layer(points, cell_size_pixels=30)
    """
    layer_id = name or f"screengrid-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    default_color_range = [
        [255, 255, 178, 25],
        [254, 217, 118, 85],
        [254, 178, 76, 127],
        [253, 141, 60, 170],
        [240, 59, 32, 212],
        [189, 0, 38, 255],
    ]

    self.call_js_method(
        "addScreenGridLayer",
        id=layer_id,
        data=processed_data,
        getPosition=get_position,
        getWeight=get_weight,
        cellSizePixels=cell_size_pixels,
        colorRange=color_range or default_color_range,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "screengrid",
        },
    }
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_search_control(self, position='top-left', placeholder='Search places...', collapsed=True, fly_to_zoom=14, show_marker=True, marker_color='#4264fb', **kwargs)

Add a search/geocoder control using Nominatim.

Provides place search functionality with autocomplete results. Results are geocoded via OpenStreetMap Nominatim service.

Parameters:

Name Type Description Default
position str

Control position ('top-left', 'top-right', 'bottom-left', 'bottom-right').

'top-left'
placeholder str

Placeholder text for the search input.

'Search places...'
collapsed bool

Whether the control starts collapsed (icon only).

True
fly_to_zoom int

Zoom level to fly to when selecting a result.

14
show_marker bool

Whether to add a marker at the selected location.

True
marker_color str

Color of the result marker.

'#4264fb'
**kwargs

Additional SearchControl options.

{}

Examples:

>>> m = Map()
>>> m.add_search_control(position="top-left", fly_to_zoom=12)
Source code in anymap_ts/maplibre.py
def add_search_control(
    self,
    position: str = "top-left",
    placeholder: str = "Search places...",
    collapsed: bool = True,
    fly_to_zoom: int = 14,
    show_marker: bool = True,
    marker_color: str = "#4264fb",
    **kwargs,
) -> None:
    """Add a search/geocoder control using Nominatim.

    Provides place search functionality with autocomplete results.
    Results are geocoded via OpenStreetMap Nominatim service.

    Args:
        position: Control position ('top-left', 'top-right',
            'bottom-left', 'bottom-right').
        placeholder: Placeholder text for the search input.
        collapsed: Whether the control starts collapsed (icon only).
        fly_to_zoom: Zoom level to fly to when selecting a result.
        show_marker: Whether to add a marker at the selected location.
        marker_color: Color of the result marker.
        **kwargs: Additional SearchControl options.

    Example:
        >>> m = Map()
        >>> m.add_search_control(position="top-left", fly_to_zoom=12)
    """
    self._validate_position(position)
    self.call_js_method(
        "addSearchControl",
        position=position,
        placeholder=placeholder,
        collapsed=collapsed,
        flyToZoom=fly_to_zoom,
        showMarker=show_marker,
        markerColor=marker_color,
        **kwargs,
    )
    self._controls = {
        **self._controls,
        "search-control": {
            "type": "search-control",
            "position": position,
            "collapsed": collapsed,
        },
    }

add_solid_polygon_layer(self, data, name=None, get_polygon='polygon', get_fill_color=None, get_line_color=None, get_elevation=0, filled=True, extruded=False, wireframe=False, elevation_scale=1, pickable=True, opacity=0.8, **kwargs)

Add a solid polygon layer for extruded 3D polygon visualization using deck.gl.

Parameters:

Name Type Description Default
data Any

Array of data objects with polygon coordinates.

required
name Optional[str]

Layer ID. If None, auto-generated.

None
get_polygon Union[str, Any]

Accessor for polygon coordinates.

'polygon'
get_fill_color Optional[Union[List[int], str]]

Accessor for fill color [r, g, b, a].

None
get_line_color Optional[Union[List[int], str]]

Accessor for stroke color [r, g, b, a].

None
get_elevation Union[float, str]

Accessor for 3D extrusion height.

0
filled bool

Whether to fill polygons.

True
extruded bool

Whether to render as 3D polygons.

False
wireframe bool

Whether to render wireframe.

False
elevation_scale float

Elevation multiplier.

1
pickable bool

Whether layer responds to hover/click events.

True
opacity float

Layer opacity (0-1).

0.8
**kwargs

Additional SolidPolygonLayer props.

{}

Examples:

>>> from anymap_ts import MapLibreMap
>>> m = MapLibreMap(pitch=45)
>>> data = [
...     {"polygon": [[-122.4, 37.8], [-122.5, 37.7], [-122.3, 37.7]], "height": 500},
... ]
>>> m.add_solid_polygon_layer(data, extruded=True, get_elevation="height")
Source code in anymap_ts/maplibre.py
def add_solid_polygon_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_polygon: Union[str, Any] = "polygon",
    get_fill_color: Optional[Union[List[int], str]] = None,
    get_line_color: Optional[Union[List[int], str]] = None,
    get_elevation: Union[float, str] = 0,
    filled: bool = True,
    extruded: bool = False,
    wireframe: bool = False,
    elevation_scale: float = 1,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add a solid polygon layer for extruded 3D polygon visualization using deck.gl.

    Args:
        data: Array of data objects with polygon coordinates.
        name: Layer ID. If None, auto-generated.
        get_polygon: Accessor for polygon coordinates.
        get_fill_color: Accessor for fill color [r, g, b, a].
        get_line_color: Accessor for stroke color [r, g, b, a].
        get_elevation: Accessor for 3D extrusion height.
        filled: Whether to fill polygons.
        extruded: Whether to render as 3D polygons.
        wireframe: Whether to render wireframe.
        elevation_scale: Elevation multiplier.
        pickable: Whether layer responds to hover/click events.
        opacity: Layer opacity (0-1).
        **kwargs: Additional SolidPolygonLayer props.

    Example:
        >>> from anymap_ts import MapLibreMap
        >>> m = MapLibreMap(pitch=45)
        >>> data = [
        ...     {"polygon": [[-122.4, 37.8], [-122.5, 37.7], [-122.3, 37.7]], "height": 500},
        ... ]
        >>> m.add_solid_polygon_layer(data, extruded=True, get_elevation="height")
    """
    layer_id = name or f"solidpolygon-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addSolidPolygonLayer",
        id=layer_id,
        data=processed_data,
        getPolygon=get_polygon,
        getFillColor=get_fill_color or [51, 136, 255, 128],
        getLineColor=get_line_color or [0, 0, 0, 255],
        getElevation=get_elevation,
        filled=filled,
        extruded=extruded,
        wireframe=wireframe,
        elevationScale=elevation_scale,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {"id": layer_id, "type": "solidpolygon"},
    }
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_split_map(self, left_layer, right_layer, position=50)

Add a split map comparison view with a draggable divider.

Creates a side-by-side comparison of two layers. The left side shows the left layer and the right side shows the right layer, with a draggable slider to adjust the split position.

Parameters:

Name Type Description Default
left_layer str

Layer ID for the left side.

required
right_layer str

Layer ID for the right side.

required
position int

Initial slider position as percentage (0-100). Default is 50 (middle).

50

Note

Both layers must exist on the map before calling this method. Best suited for raster tile layers (e.g., satellite vs streets).

Examples:

>>> m.add_tile_layer(
...     "https://mt1.google.com/vt/lyrs=s&x={x}&y={y}&z={z}",
...     name="satellite",
... )
>>> m.add_tile_layer(
...     "https://tile.openstreetmap.org/{z}/{x}/{y}.png",
...     name="osm",
... )
>>> m.add_split_map("satellite", "osm")
Source code in anymap_ts/maplibre.py
def add_split_map(
    self,
    left_layer: str,
    right_layer: str,
    position: int = 50,
) -> None:
    """Add a split map comparison view with a draggable divider.

    Creates a side-by-side comparison of two layers. The left side shows
    the left layer and the right side shows the right layer, with a
    draggable slider to adjust the split position.

    Args:
        left_layer: Layer ID for the left side.
        right_layer: Layer ID for the right side.
        position: Initial slider position as percentage (0-100).
            Default is 50 (middle).

    Note:
        Both layers must exist on the map before calling this method.
        Best suited for raster tile layers (e.g., satellite vs streets).

    Example:
        >>> m.add_tile_layer(
        ...     "https://mt1.google.com/vt/lyrs=s&x={x}&y={y}&z={z}",
        ...     name="satellite",
        ... )
        >>> m.add_tile_layer(
        ...     "https://tile.openstreetmap.org/{z}/{x}/{y}.png",
        ...     name="osm",
        ... )
        >>> m.add_split_map("satellite", "osm")
    """
    if not 0 <= position <= 100:
        raise ValueError(f"position must be between 0 and 100, got {position}")

    self.call_js_method(
        "addSplitMap",
        leftLayer=left_layer,
        rightLayer=right_layer,
        position=position,
    )

add_stac_layer(self, url=None, item=None, assets=None, colormap=None, rescale=None, opacity=1.0, layer_id=None, titiler_endpoint='https://titiler.xyz', attribution='STAC', fit_bounds=True, **kwargs)

Add a STAC (SpatioTemporal Asset Catalog) layer to the map.

Uses TiTiler to render STAC items as XYZ tiles on the map. Supports both STAC item URLs and pystac Item objects.

Parameters:

Name Type Description Default
url Optional[str]

URL to a STAC item JSON

None
item Optional[Any]

A pystac Item object

None
assets Optional[List[str]]

List of asset names/bands to visualize

None
colormap Optional[str]

Colormap name (e.g., 'viridis', 'plasma', 'inferno')

None
rescale Optional[List[float]]

Min/max values for rescaling as [min, max]

None
opacity float

Layer opacity (0-1)

1.0
layer_id Optional[str]

Custom layer identifier

None
titiler_endpoint str

TiTiler server endpoint URL

'https://titiler.xyz'
attribution str

Attribution text for the layer

'STAC'
fit_bounds bool

Whether to fit map to STAC item bounds

True
**kwargs

Additional tile layer options

{}

Examples:

>>> from anymap_ts import Map
>>> m = Map()
>>> # From URL
>>> m.add_stac_layer(
...     url="https://planetarycomputer.microsoft.com/api/stac/v1/collections/sentinel-2-l2a/items/S2A_MSIL2A_20220101T181901_N0301_R027_T10TEM_20220101T201906",
...     assets=["red", "green", "blue"],
...     rescale=[0, 3000]
... )
>>> # From pystac Item
>>> import pystac
>>> item = pystac.Item.from_file("path/to/item.json")
>>> m.add_stac_layer(item=item, assets=["nir", "red"], colormap="ndvi")
Source code in anymap_ts/maplibre.py
def add_stac_layer(
    self,
    url: Optional[str] = None,
    item: Optional[Any] = None,
    assets: Optional[List[str]] = None,
    colormap: Optional[str] = None,
    rescale: Optional[List[float]] = None,
    opacity: float = 1.0,
    layer_id: Optional[str] = None,
    titiler_endpoint: str = "https://titiler.xyz",
    attribution: str = "STAC",
    fit_bounds: bool = True,
    **kwargs,
) -> None:
    """Add a STAC (SpatioTemporal Asset Catalog) layer to the map.

    Uses TiTiler to render STAC items as XYZ tiles on the map.
    Supports both STAC item URLs and pystac Item objects.

    Args:
        url: URL to a STAC item JSON
        item: A pystac Item object
        assets: List of asset names/bands to visualize
        colormap: Colormap name (e.g., 'viridis', 'plasma', 'inferno')
        rescale: Min/max values for rescaling as [min, max]
        opacity: Layer opacity (0-1)
        layer_id: Custom layer identifier
        titiler_endpoint: TiTiler server endpoint URL
        attribution: Attribution text for the layer
        fit_bounds: Whether to fit map to STAC item bounds
        **kwargs: Additional tile layer options

    Example:
        >>> from anymap_ts import Map
        >>> m = Map()
        >>> # From URL
        >>> m.add_stac_layer(
        ...     url="https://planetarycomputer.microsoft.com/api/stac/v1/collections/sentinel-2-l2a/items/S2A_MSIL2A_20220101T181901_N0301_R027_T10TEM_20220101T201906",
        ...     assets=["red", "green", "blue"],
        ...     rescale=[0, 3000]
        ... )
        >>> # From pystac Item
        >>> import pystac
        >>> item = pystac.Item.from_file("path/to/item.json")
        >>> m.add_stac_layer(item=item, assets=["nir", "red"], colormap="ndvi")
    """
    if url is None and item is None:
        raise ValueError("Either 'url' or 'item' must be provided")

    if url is not None and item is not None:
        raise ValueError("Provide either 'url' or 'item', not both")

    # Handle pystac Item object
    if item is not None:
        try:
            # Check if it's a pystac Item
            if hasattr(item, "to_dict") and hasattr(item, "self_href"):
                stac_url = item.self_href
                if not stac_url:
                    # Try to get URL from item properties if no self_href
                    if hasattr(item, "links"):
                        for link in item.links:
                            if link.rel == "self":
                                stac_url = link.href
                                break
                    if not stac_url:
                        raise ValueError(
                            "STAC item must have a self_href or self link for tile generation"
                        )
            else:
                raise ValueError(
                    "Item must be a pystac Item object with to_dict() and self_href attributes"
                )
        except Exception as e:
            raise ValueError(f"Invalid STAC item: {e}")
    else:
        stac_url = url

    # Build TiTiler tile URL
    tile_params = {"url": stac_url}

    if assets:
        tile_params["assets"] = ",".join(assets)
    if colormap:
        tile_params["colormap_name"] = colormap
    if rescale:
        if len(rescale) == 2:
            tile_params["rescale"] = f"{rescale[0]},{rescale[1]}"
        else:
            raise ValueError("rescale must be a list of two values [min, max]")

    # Construct tile URL template
    query_string = urlencode(tile_params)
    tile_url = f"{titiler_endpoint.rstrip('/')}/stac/tiles/{{z}}/{{x}}/{{y}}?{query_string}"

    layer_name = layer_id or f"stac-{len(self._layers)}"

    # Add as tile layer
    self.add_tile_layer(
        url=tile_url,
        name=layer_name,
        attribution=attribution,
        **kwargs,
    )

    # Update layer info to mark as STAC
    if layer_name in self._layers:
        self._layers[layer_name].update(
            {
                "stac_url": stac_url,
                "stac_assets": assets,
                "colormap": colormap,
                "rescale": rescale,
            }
        )

    # Try to fit bounds if requested and we have an item object
    if fit_bounds and item is not None:
        try:
            bbox = item.bbox
            if bbox and len(bbox) == 4:
                self.fit_bounds([[bbox[0], bbox[1]], [bbox[2], bbox[3]]])
        except Exception:
            pass  # Skip bounds fitting if bbox is not available

add_style_switcher(self, styles, position='top-right')

Add a dropdown to switch between map styles.

Parameters:

Name Type Description Default
styles Dict[str, str]

Dict mapping style names to style URLs.

required
position str

Control position.

'top-right'

Examples:

>>> m = MapLibreMap()
>>> m.add_style_switcher({
...     "Light": "https://basemaps.cartocdn.com/gl/positron-gl-style/style.json",
...     "Dark": "https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json",
...     "Voyager": "https://basemaps.cartocdn.com/gl/voyager-gl-style/style.json",
... })
Source code in anymap_ts/maplibre.py
def add_style_switcher(
    self,
    styles: Dict[str, str],
    position: str = "top-right",
) -> None:
    """Add a dropdown to switch between map styles.

    Args:
        styles: Dict mapping style names to style URLs.
        position: Control position.

    Example:
        >>> m = MapLibreMap()
        >>> m.add_style_switcher({
        ...     "Light": "https://basemaps.cartocdn.com/gl/positron-gl-style/style.json",
        ...     "Dark": "https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json",
        ...     "Voyager": "https://basemaps.cartocdn.com/gl/voyager-gl-style/style.json",
        ... })
    """
    self.call_js_method(
        "addStyleSwitcher",
        styles=styles,
        position=position,
    )

add_swipe_map(self, left_layer, right_layer)

Add a drag-to-compare swipe control for two layers.

Unlike split map which is side-by-side, swipe map overlays both layers and uses a draggable divider for before/after comparison.

Parameters:

Name Type Description Default
left_layer str

Layer ID for the left side.

required
right_layer str

Layer ID for the right side.

required

Examples:

>>> m = MapLibreMap()
>>> m.add_tile_layer("...", name="before")
>>> m.add_tile_layer("...", name="after")
>>> m.add_swipe_map("before", "after")
Source code in anymap_ts/maplibre.py
def add_swipe_map(self, left_layer: str, right_layer: str) -> None:
    """Add a drag-to-compare swipe control for two layers.

    Unlike split map which is side-by-side, swipe map overlays both
    layers and uses a draggable divider for before/after comparison.

    Args:
        left_layer: Layer ID for the left side.
        right_layer: Layer ID for the right side.

    Example:
        >>> m = MapLibreMap()
        >>> m.add_tile_layer("...", name="before")
        >>> m.add_tile_layer("...", name="after")
        >>> m.add_swipe_map("before", "after")
    """
    self.call_js_method(
        "addSwipeMap",
        leftLayer=left_layer,
        rightLayer=right_layer,
    )

add_text_layer(self, data, name=None, get_position='coordinates', get_text='text', get_size=12, get_color=None, get_angle=0, text_anchor='middle', alignment_baseline='center', pickable=True, opacity=1, **kwargs)

Add a text layer for label placement using deck.gl.

Text layers render text labels at specified positions, ideal for annotating map features or creating label layers.

Parameters:

Name Type Description Default
data Any

Array of data objects with position and text.

required
name Optional[str]

Layer ID. If None, auto-generated.

None
get_position Union[str, Any]

Accessor for text position [lng, lat].

'coordinates'
get_text Union[str, Any]

Accessor for text content string.

'text'
get_size Union[float, str]

Accessor for text size in pixels.

12
get_color Optional[Union[List[int], str]]

Accessor for text color [r, g, b, a]. Default: [0, 0, 0, 255] (black).

None
get_angle Union[float, str]

Accessor for text rotation in degrees.

0
text_anchor str

Horizontal alignment ('start', 'middle', 'end').

'middle'
alignment_baseline str

Vertical alignment ('top', 'center', 'bottom').

'center'
pickable bool

Whether layer responds to hover/click events.

True
opacity float

Layer opacity (0-1).

1
**kwargs

Additional TextLayer props.

{}

Examples:

>>> from anymap_ts import MapLibreMap
>>> m = MapLibreMap()
>>> labels = [
...     {"coordinates": [-122.4, 37.8], "text": "San Francisco"},
...     {"coordinates": [-118.2, 34.1], "text": "Los Angeles"},
... ]
>>> m.add_text_layer(labels, get_size=16)
Source code in anymap_ts/maplibre.py
def add_text_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_position: Union[str, Any] = "coordinates",
    get_text: Union[str, Any] = "text",
    get_size: Union[float, str] = 12,
    get_color: Optional[Union[List[int], str]] = None,
    get_angle: Union[float, str] = 0,
    text_anchor: str = "middle",
    alignment_baseline: str = "center",
    pickable: bool = True,
    opacity: float = 1,
    **kwargs,
) -> None:
    """Add a text layer for label placement using deck.gl.

    Text layers render text labels at specified positions, ideal for
    annotating map features or creating label layers.

    Args:
        data: Array of data objects with position and text.
        name: Layer ID. If None, auto-generated.
        get_position: Accessor for text position [lng, lat].
        get_text: Accessor for text content string.
        get_size: Accessor for text size in pixels.
        get_color: Accessor for text color [r, g, b, a].
            Default: [0, 0, 0, 255] (black).
        get_angle: Accessor for text rotation in degrees.
        text_anchor: Horizontal alignment ('start', 'middle', 'end').
        alignment_baseline: Vertical alignment ('top', 'center', 'bottom').
        pickable: Whether layer responds to hover/click events.
        opacity: Layer opacity (0-1).
        **kwargs: Additional TextLayer props.

    Example:
        >>> from anymap_ts import MapLibreMap
        >>> m = MapLibreMap()
        >>> labels = [
        ...     {"coordinates": [-122.4, 37.8], "text": "San Francisco"},
        ...     {"coordinates": [-118.2, 34.1], "text": "Los Angeles"},
        ... ]
        >>> m.add_text_layer(labels, get_size=16)
    """
    layer_id = name or f"text-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addTextLayer",
        id=layer_id,
        data=processed_data,
        getPosition=get_position,
        getText=get_text,
        getSize=get_size,
        getColor=get_color or [0, 0, 0, 255],
        getAngle=get_angle,
        getTextAnchor=text_anchor,
        getAlignmentBaseline=alignment_baseline,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "text",
        },
    }
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_tile_layer(self, url, name=None, attribution='', min_zoom=0, max_zoom=22, **kwargs)

Add an XYZ tile layer.

Parameters:

Name Type Description Default
url str

Tile URL template with {x}, {y}, {z} placeholders

required
name Optional[str]

Layer name

None
attribution str

Attribution text

''
min_zoom int

Minimum zoom level

0
max_zoom int

Maximum zoom level

22
**kwargs

Additional options

{}
Source code in anymap_ts/maplibre.py
def add_tile_layer(
    self,
    url: str,
    name: Optional[str] = None,
    attribution: str = "",
    min_zoom: int = 0,
    max_zoom: int = 22,
    **kwargs,
) -> None:
    """Add an XYZ tile layer.

    Args:
        url: Tile URL template with {x}, {y}, {z} placeholders
        name: Layer name
        attribution: Attribution text
        min_zoom: Minimum zoom level
        max_zoom: Maximum zoom level
        **kwargs: Additional options
    """
    layer_id = name or f"tiles-{len(self._layers)}"

    self.call_js_method(
        "addTileLayer",
        url,
        name=layer_id,
        attribution=attribution,
        minZoom=min_zoom,
        maxZoom=max_zoom,
        **kwargs,
    )

    # Track layer
    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "raster",
            "source": f"{layer_id}-source",
        },
    }
    self._add_to_layer_dict(layer_id, "Raster")

add_time_slider(self, layer_id, property, min_value=0, max_value=100, step=1, position='bottom-left', label='Time', auto_play=False, interval=500)

Add a time slider to filter data by a temporal property.

Creates a slider control that filters layer features based on a numeric/temporal property, with optional auto-animation.

Parameters:

Name Type Description Default
layer_id str

Layer ID to filter.

required
property str

Property name to filter on.

required
min_value float

Minimum slider value.

0
max_value float

Maximum slider value.

100
step float

Step increment.

1
position str

Control position.

'bottom-left'
label str

Label text for the slider.

'Time'
auto_play bool

Whether to auto-animate through values.

False
interval int

Animation interval in milliseconds.

500

Examples:

>>> m = MapLibreMap()
>>> m.add_geojson("events.geojson", name="events")
>>> m.add_time_slider("events", "year", min_value=2000, max_value=2024)
Source code in anymap_ts/maplibre.py
def add_time_slider(
    self,
    layer_id: str,
    property: str,
    min_value: float = 0,
    max_value: float = 100,
    step: float = 1,
    position: str = "bottom-left",
    label: str = "Time",
    auto_play: bool = False,
    interval: int = 500,
) -> None:
    """Add a time slider to filter data by a temporal property.

    Creates a slider control that filters layer features based on a
    numeric/temporal property, with optional auto-animation.

    Args:
        layer_id: Layer ID to filter.
        property: Property name to filter on.
        min_value: Minimum slider value.
        max_value: Maximum slider value.
        step: Step increment.
        position: Control position.
        label: Label text for the slider.
        auto_play: Whether to auto-animate through values.
        interval: Animation interval in milliseconds.

    Example:
        >>> m = MapLibreMap()
        >>> m.add_geojson("events.geojson", name="events")
        >>> m.add_time_slider("events", "year", min_value=2000, max_value=2024)
    """
    self.call_js_method(
        "addTimeSlider",
        layerId=layer_id,
        property=property,
        min=min_value,
        max=max_value,
        step=step,
        position=position,
        label=label,
        autoPlay=auto_play,
        interval=interval,
    )

add_tooltip(self, layer_id, template=None, properties=None)

Add a tooltip that shows on feature hover.

Shows formatted information when hovering over features in a layer.

Parameters:

Name Type Description Default
layer_id str

The ID of the layer to add tooltips to.

required
template Optional[str]

HTML template with {property} placeholders. Example: "Name: {name}
Population: {pop}".

None
properties Optional[List[str]]

List of property names to display. If None and no template, all properties are shown.

None

Examples:

>>> m = MapLibreMap()
>>> m.add_geojson("data.geojson", name="cities")
>>> m.add_tooltip("cities", template="<b>{name}</b><br>Pop: {population}")
Source code in anymap_ts/maplibre.py
def add_tooltip(
    self,
    layer_id: str,
    template: Optional[str] = None,
    properties: Optional[List[str]] = None,
) -> None:
    """Add a tooltip that shows on feature hover.

    Shows formatted information when hovering over features in a layer.

    Args:
        layer_id: The ID of the layer to add tooltips to.
        template: HTML template with {property} placeholders.
            Example: "Name: {name}<br>Population: {pop}".
        properties: List of property names to display. If None and no
            template, all properties are shown.

    Example:
        >>> m = MapLibreMap()
        >>> m.add_geojson("data.geojson", name="cities")
        >>> m.add_tooltip("cities", template="<b>{name}</b><br>Pop: {population}")
    """
    self.call_js_method(
        "addTooltip",
        layerId=layer_id,
        template=template or "",
        properties=properties,
    )

add_trips_layer(self, data, name=None, get_path='waypoints', get_timestamps='timestamps', get_color=None, width_min_pixels=2, trail_length=180, current_time=0, pickable=True, opacity=0.8, **kwargs)

Add a trips layer for animated trip/trajectory playback using deck.gl.

Trips layers render animated paths showing movement over time, ideal for visualizing vehicle routes, migration patterns, or time-based data.

Parameters:

Name Type Description Default
data Any

Array of trip objects with waypoints and timestamps.

required
name Optional[str]

Layer ID. If None, auto-generated.

None
get_path Union[str, Any]

Accessor for waypoint coordinates [[lng, lat], ...].

'waypoints'
get_timestamps Union[str, Any]

Accessor for timestamps at each waypoint.

'timestamps'
get_color Optional[Union[List[int], str]]

Accessor for trip color [r, g, b] or [r, g, b, a]. Default: [253, 128, 93].

None
width_min_pixels float

Minimum trail width in pixels.

2
trail_length float

Trail length in timestamp units.

180
current_time float

Current animation time.

0
pickable bool

Whether layer responds to hover/click events.

True
opacity float

Layer opacity (0-1).

0.8
**kwargs

Additional TripsLayer props.

{}

Examples:

>>> from anymap_ts import MapLibreMap
>>> m = MapLibreMap()
>>> trips = [
...     {
...         "waypoints": [[-122.4, 37.8], [-122.5, 37.7]],
...         "timestamps": [0, 100]
...     }
... ]
>>> m.add_trips_layer(trips, trail_length=200, current_time=50)
Source code in anymap_ts/maplibre.py
def add_trips_layer(
    self,
    data: Any,
    name: Optional[str] = None,
    get_path: Union[str, Any] = "waypoints",
    get_timestamps: Union[str, Any] = "timestamps",
    get_color: Optional[Union[List[int], str]] = None,
    width_min_pixels: float = 2,
    trail_length: float = 180,
    current_time: float = 0,
    pickable: bool = True,
    opacity: float = 0.8,
    **kwargs,
) -> None:
    """Add a trips layer for animated trip/trajectory playback using deck.gl.

    Trips layers render animated paths showing movement over time, ideal
    for visualizing vehicle routes, migration patterns, or time-based data.

    Args:
        data: Array of trip objects with waypoints and timestamps.
        name: Layer ID. If None, auto-generated.
        get_path: Accessor for waypoint coordinates [[lng, lat], ...].
        get_timestamps: Accessor for timestamps at each waypoint.
        get_color: Accessor for trip color [r, g, b] or [r, g, b, a].
            Default: [253, 128, 93].
        width_min_pixels: Minimum trail width in pixels.
        trail_length: Trail length in timestamp units.
        current_time: Current animation time.
        pickable: Whether layer responds to hover/click events.
        opacity: Layer opacity (0-1).
        **kwargs: Additional TripsLayer props.

    Example:
        >>> from anymap_ts import MapLibreMap
        >>> m = MapLibreMap()
        >>> trips = [
        ...     {
        ...         "waypoints": [[-122.4, 37.8], [-122.5, 37.7]],
        ...         "timestamps": [0, 100]
        ...     }
        ... ]
        >>> m.add_trips_layer(trips, trail_length=200, current_time=50)
    """
    layer_id = name or f"trips-{len(self._layers)}"
    processed_data = self._process_deck_data(data)

    self.call_js_method(
        "addTripsLayer",
        id=layer_id,
        data=processed_data,
        getPath=get_path,
        getTimestamps=get_timestamps,
        getColor=get_color or [253, 128, 93],
        widthMinPixels=width_min_pixels,
        trailLength=trail_length,
        currentTime=current_time,
        pickable=pickable,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "trips",
        },
    }
    self._add_to_layer_dict(layer_id, "Deck.gl")

add_vector(self, data, layer_type=None, paint=None, name=None, fit_bounds=True, **kwargs)

Add vector data to the map.

Supports GeoJSON, GeoDataFrame, or file paths to vector formats.

Parameters:

Name Type Description Default
data Any

GeoJSON dict, GeoDataFrame, or path to vector file

required
layer_type Optional[str]

MapLibre layer type ('circle', 'line', 'fill', 'symbol')

None
paint Optional[Dict]

MapLibre paint properties

None
name Optional[str]

Layer name

None
fit_bounds bool

Whether to fit map to data bounds

True
**kwargs

Additional layer options

{}
Source code in anymap_ts/maplibre.py
def add_vector(
    self,
    data: Any,
    layer_type: Optional[str] = None,
    paint: Optional[Dict] = None,
    name: Optional[str] = None,
    fit_bounds: bool = True,
    **kwargs,
) -> None:
    """Add vector data to the map.

    Supports GeoJSON, GeoDataFrame, or file paths to vector formats.

    Args:
        data: GeoJSON dict, GeoDataFrame, or path to vector file
        layer_type: MapLibre layer type ('circle', 'line', 'fill', 'symbol')
        paint: MapLibre paint properties
        name: Layer name
        fit_bounds: Whether to fit map to data bounds
        **kwargs: Additional layer options
    """
    geojson = to_geojson(data)

    layer_id = name or f"vector-{len(self._layers)}"

    # Handle URL data - fetch GeoJSON to get bounds and infer layer type
    if geojson.get("type") == "url":
        url = geojson["url"]
        # Fetch the actual GeoJSON data from URL
        geojson = fetch_geojson(url)

    # Infer layer type if not specified
    if layer_type is None:
        layer_type = infer_layer_type(geojson)

    # Get default paint if not provided
    if paint is None:
        paint = get_default_paint(layer_type)

    # Get bounds (use geojson dict, not original data which may be a URL)
    bounds = get_bounds(geojson) if fit_bounds else None

    # Call JavaScript
    self.call_js_method(
        "addGeoJSON",
        data=geojson,
        name=layer_id,
        layerType=layer_type,
        paint=paint,
        fitBounds=fit_bounds,
        bounds=bounds,
        **kwargs,
    )

    # Track layer
    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": layer_type,
            "source": f"{layer_id}-source",
            "paint": paint,
        },
    }
    self._add_to_layer_dict(layer_id, "Vector")

add_vector_control(self, position='top-right', collapsed=True, default_url=None, load_default_url=False, default_opacity=1.0, default_fill_color='#3388ff', default_stroke_color='#3388ff', fit_bounds=True, **kwargs)

Add a vector layer control for loading vector datasets from URLs.

This provides an interactive panel for users to enter URLs to GeoJSON, GeoParquet, or FlatGeobuf datasets.

Parameters:

Name Type Description Default
position str

Control position ('top-left', 'top-right', 'bottom-left', 'bottom-right').

'top-right'
collapsed bool

Whether the panel starts collapsed.

True
default_url Optional[str]

Default vector URL to pre-fill.

None
load_default_url bool

Whether to auto-load the default URL.

False
default_opacity float

Default layer opacity (0-1).

1.0
default_fill_color str

Default fill color for polygons.

'#3388ff'
default_stroke_color str

Default stroke color for lines/outlines.

'#3388ff'
fit_bounds bool

Whether to fit map to loaded data bounds.

True
**kwargs

Additional control options.

{}

Examples:

>>> from anymap_ts import MapLibreMap
>>> m = MapLibreMap()
>>> m.add_vector_control(
...     default_url="https://example.com/data.geojson",
...     default_fill_color="#ff0000"
... )
Source code in anymap_ts/maplibre.py
def add_vector_control(
    self,
    position: str = "top-right",
    collapsed: bool = True,
    default_url: Optional[str] = None,
    load_default_url: bool = False,
    default_opacity: float = 1.0,
    default_fill_color: str = "#3388ff",
    default_stroke_color: str = "#3388ff",
    fit_bounds: bool = True,
    **kwargs,
) -> None:
    """Add a vector layer control for loading vector datasets from URLs.

    This provides an interactive panel for users to enter URLs to
    GeoJSON, GeoParquet, or FlatGeobuf datasets.

    Args:
        position: Control position ('top-left', 'top-right', 'bottom-left', 'bottom-right').
        collapsed: Whether the panel starts collapsed.
        default_url: Default vector URL to pre-fill.
        load_default_url: Whether to auto-load the default URL.
        default_opacity: Default layer opacity (0-1).
        default_fill_color: Default fill color for polygons.
        default_stroke_color: Default stroke color for lines/outlines.
        fit_bounds: Whether to fit map to loaded data bounds.
        **kwargs: Additional control options.

    Example:
        >>> from anymap_ts import MapLibreMap
        >>> m = MapLibreMap()
        >>> m.add_vector_control(
        ...     default_url="https://example.com/data.geojson",
        ...     default_fill_color="#ff0000"
        ... )
    """
    self.call_js_method(
        "addVectorControl",
        position=position,
        collapsed=collapsed,
        defaultUrl=default_url or "",
        loadDefaultUrl=load_default_url,
        defaultOpacity=default_opacity,
        defaultFillColor=default_fill_color,
        defaultStrokeColor=default_stroke_color,
        fitBounds=fit_bounds,
        **kwargs,
    )
    self._controls = {
        **self._controls,
        "vector-control": {"position": position, "collapsed": collapsed},
    }

add_video_layer(self, urls, coordinates, name=None, opacity=1.0, **kwargs)

Add a georeferenced video overlay on the map.

Parameters:

Name Type Description Default
urls List[str]

List of video URLs (provide multiple formats for browser compatibility, e.g., [".mp4", ".webm"]).

required
coordinates List[List[float]]

Four corner coordinates as [[lng, lat], ...] in order: top-left, top-right, bottom-right, bottom-left.

required
name Optional[str]

Layer identifier. If None, auto-generated.

None
opacity float

Layer opacity (0-1). Default is 1.0.

1.0
**kwargs

Additional layer options.

{}

Examples:

>>> m.add_video_layer(
...     urls=["https://example.com/video.mp4"],
...     coordinates=[
...         [-122.51596391658498, 37.56238816766053],
...         [-122.51467645489949, 37.56410183312965],
...         [-122.51309394645498, 37.563391708549425],
...         [-122.51423120498498, 37.56161849366671],
...     ],
... )
Source code in anymap_ts/maplibre.py
def add_video_layer(
    self,
    urls: List[str],
    coordinates: List[List[float]],
    name: Optional[str] = None,
    opacity: float = 1.0,
    **kwargs,
) -> None:
    """Add a georeferenced video overlay on the map.

    Args:
        urls: List of video URLs (provide multiple formats for browser
            compatibility, e.g., [".mp4", ".webm"]).
        coordinates: Four corner coordinates as [[lng, lat], ...] in order:
            top-left, top-right, bottom-right, bottom-left.
        name: Layer identifier. If None, auto-generated.
        opacity: Layer opacity (0-1). Default is 1.0.
        **kwargs: Additional layer options.

    Example:
        >>> m.add_video_layer(
        ...     urls=["https://example.com/video.mp4"],
        ...     coordinates=[
        ...         [-122.51596391658498, 37.56238816766053],
        ...         [-122.51467645489949, 37.56410183312965],
        ...         [-122.51309394645498, 37.563391708549425],
        ...         [-122.51423120498498, 37.56161849366671],
        ...     ],
        ... )
    """
    self._validate_opacity(opacity)
    layer_id = name or f"video-{len(self._layers)}"

    if len(coordinates) != 4:
        raise ValueError(
            "coordinates must have exactly 4 corner points "
            "[top-left, top-right, bottom-right, bottom-left]"
        )

    self.call_js_method(
        "addVideoLayer",
        id=layer_id,
        urls=urls,
        coordinates=coordinates,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "video",
            "source": f"{layer_id}-source",
        },
    }
    self._add_to_layer_dict(layer_id, "Raster")

add_zarr_control(self, position='top-right', collapsed=True, default_url=None, load_default_url=False, default_opacity=1.0, default_variable='', default_clim=None, **kwargs)

Add a Zarr layer control for loading Zarr datasets via UI.

This provides an interactive panel for users to enter Zarr URLs and configure visualization parameters.

Parameters:

Name Type Description Default
position str

Control position ('top-left', 'top-right', 'bottom-left', 'bottom-right').

'top-right'
collapsed bool

Whether the panel starts collapsed.

True
default_url Optional[str]

Default Zarr URL to pre-fill.

None
load_default_url bool

Whether to auto-load the default URL.

False
default_opacity float

Default layer opacity (0-1).

1.0
default_variable str

Default variable name.

''
default_clim Optional[Tuple[float, float]]

Default color limits (min, max).

None
**kwargs

Additional control options.

{}

Examples:

>>> from anymap_ts import MapLibreMap
>>> m = MapLibreMap()
>>> m.add_zarr_control(
...     default_url="https://example.com/data.zarr",
...     default_variable="temperature"
... )
Source code in anymap_ts/maplibre.py
def add_zarr_control(
    self,
    position: str = "top-right",
    collapsed: bool = True,
    default_url: Optional[str] = None,
    load_default_url: bool = False,
    default_opacity: float = 1.0,
    default_variable: str = "",
    default_clim: Optional[Tuple[float, float]] = None,
    **kwargs,
) -> None:
    """Add a Zarr layer control for loading Zarr datasets via UI.

    This provides an interactive panel for users to enter Zarr URLs
    and configure visualization parameters.

    Args:
        position: Control position ('top-left', 'top-right', 'bottom-left', 'bottom-right').
        collapsed: Whether the panel starts collapsed.
        default_url: Default Zarr URL to pre-fill.
        load_default_url: Whether to auto-load the default URL.
        default_opacity: Default layer opacity (0-1).
        default_variable: Default variable name.
        default_clim: Default color limits (min, max).
        **kwargs: Additional control options.

    Example:
        >>> from anymap_ts import MapLibreMap
        >>> m = MapLibreMap()
        >>> m.add_zarr_control(
        ...     default_url="https://example.com/data.zarr",
        ...     default_variable="temperature"
        ... )
    """
    self.call_js_method(
        "addZarrControl",
        position=position,
        collapsed=collapsed,
        defaultUrl=default_url or "",
        loadDefaultUrl=load_default_url,
        defaultOpacity=default_opacity,
        defaultVariable=default_variable,
        defaultClim=list(default_clim) if default_clim else [0, 1],
        **kwargs,
    )
    self._controls = {
        **self._controls,
        "zarr-control": {"position": position, "collapsed": collapsed},
    }

add_zarr_layer(self, url, variable, name=None, colormap=None, clim=None, opacity=1.0, selector=None, minzoom=0, maxzoom=22, fill_value=None, spatial_dimensions=None, zarr_version=None, bounds=None, **kwargs)

Add a Zarr dataset layer for visualizing multidimensional array data.

This method renders Zarr pyramid datasets directly in the browser using GPU-accelerated WebGL rendering via @carbonplan/zarr-layer.

Parameters:

Name Type Description Default
url str

URL to the Zarr store (pyramid format recommended).

required
variable str

Variable name in the Zarr dataset to visualize.

required
name Optional[str]

Layer ID. If None, auto-generated.

None
colormap Optional[List[str]]

List of hex color strings for visualization. Example: ['#0000ff', '#ffff00', '#ff0000'] (blue-yellow-red). Default: ['#000000', '#ffffff'] (black to white).

None
clim Optional[Tuple[float, float]]

Color range as (min, max) tuple. Default: (0, 100).

None
opacity float

Layer opacity (0-1).

1.0
selector Optional[Dict[str, Any]]

Dimension selector for multi-dimensional data. Example: {"month": 4} to select 4th month.

None
minzoom int

Minimum zoom level for rendering.

0
maxzoom int

Maximum zoom level for rendering.

22
fill_value Optional[float]

No-data value (auto-detected from metadata if not set).

None
spatial_dimensions Optional[Dict[str, str]]

Custom spatial dimension names. Example: {"lat": "y", "lon": "x"} for non-standard names.

None
zarr_version Optional[int]

Zarr format version (2 or 3). Auto-detected if not set.

None
bounds Optional[List[float]]

Explicit spatial bounds [xMin, yMin, xMax, yMax]. Units depend on CRS: degrees for EPSG:4326, meters for EPSG:3857.

None
**kwargs

Additional ZarrLayer props.

{}

Examples:

>>> from anymap_ts import Map
>>> m = Map()
>>> m.add_zarr_layer(
...     "https://example.com/climate.zarr",
...     variable="temperature",
...     clim=(270, 310),
...     colormap=['#0000ff', '#ffff00', '#ff0000'],
...     selector={"month": 7}
... )
Source code in anymap_ts/maplibre.py
def add_zarr_layer(
    self,
    url: str,
    variable: str,
    name: Optional[str] = None,
    colormap: Optional[List[str]] = None,
    clim: Optional[Tuple[float, float]] = None,
    opacity: float = 1.0,
    selector: Optional[Dict[str, Any]] = None,
    minzoom: int = 0,
    maxzoom: int = 22,
    fill_value: Optional[float] = None,
    spatial_dimensions: Optional[Dict[str, str]] = None,
    zarr_version: Optional[int] = None,
    bounds: Optional[List[float]] = None,
    **kwargs,
) -> None:
    """Add a Zarr dataset layer for visualizing multidimensional array data.

    This method renders Zarr pyramid datasets directly in the browser using
    GPU-accelerated WebGL rendering via @carbonplan/zarr-layer.

    Args:
        url: URL to the Zarr store (pyramid format recommended).
        variable: Variable name in the Zarr dataset to visualize.
        name: Layer ID. If None, auto-generated.
        colormap: List of hex color strings for visualization.
            Example: ['#0000ff', '#ffff00', '#ff0000'] (blue-yellow-red).
            Default: ['#000000', '#ffffff'] (black to white).
        clim: Color range as (min, max) tuple.
            Default: (0, 100).
        opacity: Layer opacity (0-1).
        selector: Dimension selector for multi-dimensional data.
            Example: {"month": 4} to select 4th month.
        minzoom: Minimum zoom level for rendering.
        maxzoom: Maximum zoom level for rendering.
        fill_value: No-data value (auto-detected from metadata if not set).
        spatial_dimensions: Custom spatial dimension names.
            Example: {"lat": "y", "lon": "x"} for non-standard names.
        zarr_version: Zarr format version (2 or 3). Auto-detected if not set.
        bounds: Explicit spatial bounds [xMin, yMin, xMax, yMax].
            Units depend on CRS: degrees for EPSG:4326, meters for EPSG:3857.
        **kwargs: Additional ZarrLayer props.

    Example:
        >>> from anymap_ts import Map
        >>> m = Map()
        >>> m.add_zarr_layer(
        ...     "https://example.com/climate.zarr",
        ...     variable="temperature",
        ...     clim=(270, 310),
        ...     colormap=['#0000ff', '#ffff00', '#ff0000'],
        ...     selector={"month": 7}
        ... )
    """
    layer_id = name or f"zarr-{len(self._layers)}"

    self.call_js_method(
        "addZarrLayer",
        id=layer_id,
        source=url,
        variable=variable,
        colormap=colormap or ["#000000", "#ffffff"],
        clim=list(clim) if clim else [0, 100],
        opacity=opacity,
        selector=selector or {},
        minzoom=minzoom,
        maxzoom=maxzoom,
        fillValue=fill_value,
        spatialDimensions=spatial_dimensions,
        zarrVersion=zarr_version,
        bounds=bounds,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {
            "id": layer_id,
            "type": "zarr",
            "url": url,
            "variable": variable,
        },
    }
    self._add_to_layer_dict(layer_id, "Raster")

animate_along_route(self, route, duration=10000, loop=True, marker_color='#3388ff', marker_size=1.0, show_trail=False, trail_color='#3388ff', trail_width=3, animation_id=None, **kwargs)

Animate a marker along a route.

Creates an animated marker that moves along the specified route line.

Parameters:

Name Type Description Default
route Any

Route data - LineString GeoJSON, list of coordinates, GeoDataFrame, or file path.

required
duration int

Animation duration in milliseconds.

10000
loop bool

Whether to loop the animation.

True
marker_color str

Marker color.

'#3388ff'
marker_size float

Marker size multiplier.

1.0
show_trail bool

Whether to show a trail behind the marker.

False
trail_color str

Trail line color.

'#3388ff'
trail_width float

Trail line width.

3
animation_id Optional[str]

Animation identifier. If None, auto-generated.

None
**kwargs

Additional animation options.

{}

Returns:

Type Description
str

The animation identifier.

Examples:

>>> from anymap_ts import Map
>>> m = Map()
>>> coords = [[-122.4, 37.8], [-122.3, 37.7], [-122.2, 37.8]]
>>> anim_id = m.animate_along_route(coords, duration=5000, loop=True)
Source code in anymap_ts/maplibre.py
def animate_along_route(
    self,
    route: Any,
    duration: int = 10000,
    loop: bool = True,
    marker_color: str = "#3388ff",
    marker_size: float = 1.0,
    show_trail: bool = False,
    trail_color: str = "#3388ff",
    trail_width: float = 3,
    animation_id: Optional[str] = None,
    **kwargs,
) -> str:
    """Animate a marker along a route.

    Creates an animated marker that moves along the specified route line.

    Args:
        route: Route data - LineString GeoJSON, list of coordinates,
            GeoDataFrame, or file path.
        duration: Animation duration in milliseconds.
        loop: Whether to loop the animation.
        marker_color: Marker color.
        marker_size: Marker size multiplier.
        show_trail: Whether to show a trail behind the marker.
        trail_color: Trail line color.
        trail_width: Trail line width.
        animation_id: Animation identifier. If None, auto-generated.
        **kwargs: Additional animation options.

    Returns:
        The animation identifier.

    Example:
        >>> from anymap_ts import Map
        >>> m = Map()
        >>> coords = [[-122.4, 37.8], [-122.3, 37.7], [-122.2, 37.8]]
        >>> anim_id = m.animate_along_route(coords, duration=5000, loop=True)
    """
    anim_id = animation_id or f"animation-{len(self._layers)}"

    # Convert route to coordinates list
    if isinstance(route, list) and len(route) > 0:
        if isinstance(route[0], (list, tuple)):
            # Already a list of coordinates
            coordinates = route
        else:
            raise ValueError("Route list must contain coordinate pairs")
    elif isinstance(route, dict):
        # GeoJSON
        if route.get("type") == "LineString":
            coordinates = route.get("coordinates", [])
        elif route.get("type") == "Feature":
            geometry = route.get("geometry", {})
            if geometry.get("type") == "LineString":
                coordinates = geometry.get("coordinates", [])
            else:
                raise ValueError("Feature geometry must be LineString")
        elif route.get("type") == "FeatureCollection":
            features = route.get("features", [])
            if (
                features
                and features[0].get("geometry", {}).get("type") == "LineString"
            ):
                coordinates = features[0]["geometry"]["coordinates"]
            else:
                raise ValueError(
                    "FeatureCollection must contain LineString features"
                )
        else:
            raise ValueError(
                "GeoJSON must be LineString, Feature, or FeatureCollection"
            )
    else:
        # Try to convert using to_geojson
        geojson = to_geojson(route)
        if geojson.get("type") == "url":
            geojson = fetch_geojson(geojson["url"])
        # Extract coordinates from the converted geojson
        if geojson.get("type") == "FeatureCollection":
            features = geojson.get("features", [])
            if features:
                coordinates = features[0].get("geometry", {}).get("coordinates", [])
            else:
                raise ValueError("No features found in data")
        elif geojson.get("type") == "Feature":
            coordinates = geojson.get("geometry", {}).get("coordinates", [])
        else:
            coordinates = geojson.get("coordinates", [])

    if len(coordinates) < 2:
        raise ValueError("Route must have at least 2 points")

    self.call_js_method(
        "animateAlongRoute",
        id=anim_id,
        coordinates=coordinates,
        duration=duration,
        loop=loop,
        markerColor=marker_color,
        markerSize=marker_size,
        showTrail=show_trail,
        trailColor=trail_color,
        trailWidth=trail_width,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        anim_id: {
            "id": anim_id,
            "type": "animation",
        },
    }
    return anim_id

clear_draw_data(self)

Clear all drawn features.

Source code in anymap_ts/maplibre.py
def clear_draw_data(self) -> None:
    """Clear all drawn features."""
    self._draw_data = {"type": "FeatureCollection", "features": []}
    self.call_js_method("clearDrawData")

get_draw_data(self)

Get the current drawn features as GeoJSON.

Returns:

Type Description
Dict

GeoJSON FeatureCollection of drawn features

Source code in anymap_ts/maplibre.py
def get_draw_data(self) -> Dict:
    """Get the current drawn features as GeoJSON.

    Returns:
        GeoJSON FeatureCollection of drawn features
    """
    self.call_js_method("getDrawData")
    # Small delay to allow JS to update the trait
    import time

    time.sleep(0.1)
    return self._draw_data or {"type": "FeatureCollection", "features": []}

get_layer(self, layer_id)

Get layer configuration by ID.

Parameters:

Name Type Description Default
layer_id str

Layer identifier.

required

Returns:

Type Description
Optional[Dict]

Layer configuration dict or None if not found.

Source code in anymap_ts/maplibre.py
def get_layer(self, layer_id: str) -> Optional[Dict]:
    """Get layer configuration by ID.

    Args:
        layer_id: Layer identifier.

    Returns:
        Layer configuration dict or None if not found.
    """
    return self._layers.get(layer_id)

get_layer_ids(self)

Get list of all layer IDs.

Returns:

Type Description
List[str]

List of layer identifiers.

Source code in anymap_ts/maplibre.py
def get_layer_ids(self) -> List[str]:
    """Get list of all layer IDs.

    Returns:
        List of layer identifiers.
    """
    return list(self._layers.keys())

get_visible_features(self, layers=None)

Get all features currently visible in the viewport.

This triggers a query to the JavaScript side. The result is returned asynchronously via the _queried_features trait.

On the first call, the query is sent and None is returned because the JavaScript side has not yet responded. Run this method in one notebook cell, then read the result in the next cell (the event loop processes the response between cells).

Parameters:

Name Type Description Default
layers Optional[List[str]]

Optional list of layer IDs to query. If None, queries all visible layers.

None

Returns:

Type Description
Optional[Dict]

GeoJSON FeatureCollection dict if results are available from a previous query, otherwise None.

Examples:

>>> # Cell 1 – trigger the query
>>> m.get_visible_features(layers=["my-layer"])
>>> # Cell 2 – read the result
>>> m.get_visible_features()
Source code in anymap_ts/maplibre.py
def get_visible_features(
    self,
    layers: Optional[List[str]] = None,
) -> Optional[Dict]:
    """Get all features currently visible in the viewport.

    This triggers a query to the JavaScript side. The result is
    returned asynchronously via the ``_queried_features`` trait.

    On the first call, the query is sent and ``None`` is returned
    because the JavaScript side has not yet responded. Run this
    method in one notebook cell, then read the result in the next
    cell (the event loop processes the response between cells).

    Args:
        layers: Optional list of layer IDs to query. If ``None``,
            queries all visible layers.

    Returns:
        GeoJSON FeatureCollection dict if results are available from
        a previous query, otherwise ``None``.

    Example:
        >>> # Cell 1 – trigger the query
        >>> m.get_visible_features(layers=["my-layer"])
        >>> # Cell 2 – read the result
        >>> m.get_visible_features()
    """
    if layers is not None:
        self.call_js_method("getVisibleFeatures", layers=layers)
    features = self._queried_features
    if features and "data" in features:
        return features["data"]
    return None

load_draw_data(self, geojson)

Load GeoJSON features into the drawing layer.

Parameters:

Name Type Description Default
geojson Dict

GeoJSON FeatureCollection to load

required
Source code in anymap_ts/maplibre.py
def load_draw_data(self, geojson: Dict) -> None:
    """Load GeoJSON features into the drawing layer.

    Args:
        geojson: GeoJSON FeatureCollection to load
    """
    self._draw_data = geojson
    self.call_js_method("loadDrawData", geojson)

move_layer(self, layer_id, before_id=None)

Move a layer in the layer stack.

Parameters:

Name Type Description Default
layer_id str

Layer identifier to move.

required
before_id Optional[str]

ID of layer to move before. If None, moves to top.

None

Examples:

>>> m.move_layer("my-layer", "other-layer")  # Move before other-layer
>>> m.move_layer("my-layer")  # Move to top
Source code in anymap_ts/maplibre.py
def move_layer(self, layer_id: str, before_id: Optional[str] = None) -> None:
    """Move a layer in the layer stack.

    Args:
        layer_id: Layer identifier to move.
        before_id: ID of layer to move before. If None, moves to top.

    Example:
        >>> m.move_layer("my-layer", "other-layer")  # Move before other-layer
        >>> m.move_layer("my-layer")  # Move to top
    """
    self.call_js_method("moveLayer", layer_id, before_id)

pause_animation(self, animation_id)

Pause a running animation.

Parameters:

Name Type Description Default
animation_id str

Animation identifier to pause.

required
Source code in anymap_ts/maplibre.py
def pause_animation(self, animation_id: str) -> None:
    """Pause a running animation.

    Args:
        animation_id: Animation identifier to pause.
    """
    self.call_js_method("pauseAnimation", animation_id)

pause_video(self, name)

Pause a video layer.

Parameters:

Name Type Description Default
name str

The video layer identifier.

required
Source code in anymap_ts/maplibre.py
def pause_video(self, name: str) -> None:
    """Pause a video layer.

    Args:
        name: The video layer identifier.
    """
    self.call_js_method("pauseVideo", id=name)

play_video(self, name)

Start playing a video layer.

Parameters:

Name Type Description Default
name str

The video layer identifier.

required
Source code in anymap_ts/maplibre.py
def play_video(self, name: str) -> None:
    """Start playing a video layer.

    Args:
        name: The video layer identifier.
    """
    self.call_js_method("playVideo", id=name)

query_rendered_features(self, geometry=None, layers=None, filter_expression=None)

Query features currently rendered on the map.

Results are stored in the queried_features property.

Parameters:

Name Type Description Default
geometry Optional[Any]

Optional point {x, y} or bounding box [[x1, y1], [x2, y2]] to limit the query area. If None, queries the entire viewport.

None
layers Optional[List[str]]

Optional list of layer IDs to query. If None, queries all layers.

None
filter_expression Optional[List]

Optional MapLibre filter expression to further filter results.

None

Returns:

Type Description
Dict

The current queried features dict (may not yet reflect this query if called immediately; use the queried_features property).

Examples:

>>> m.query_rendered_features(layers=["states-layer"])
>>> features = m.queried_features
Source code in anymap_ts/maplibre.py
def query_rendered_features(
    self,
    geometry: Optional[Any] = None,
    layers: Optional[List[str]] = None,
    filter_expression: Optional[List] = None,
) -> Dict:
    """Query features currently rendered on the map.

    Results are stored in the `queried_features` property.

    Args:
        geometry: Optional point {x, y} or bounding box [[x1, y1], [x2, y2]]
            to limit the query area. If None, queries the entire viewport.
        layers: Optional list of layer IDs to query. If None, queries all
            layers.
        filter_expression: Optional MapLibre filter expression to further
            filter results.

    Returns:
        The current queried features dict (may not yet reflect this query
        if called immediately; use the `queried_features` property).

    Example:
        >>> m.query_rendered_features(layers=["states-layer"])
        >>> features = m.queried_features
    """
    kwargs: Dict[str, Any] = {}
    if geometry is not None:
        kwargs["geometry"] = geometry
    if layers is not None:
        kwargs["layers"] = layers
    if filter_expression is not None:
        kwargs["filter"] = filter_expression

    self.call_js_method("queryRenderedFeatures", **kwargs)
    return self._queried_features

query_source_features(self, source_id, source_layer=None, filter_expression=None)

Query features from a source, including features not currently visible.

Results are stored in the queried_features property.

Parameters:

Name Type Description Default
source_id str

The source to query.

required
source_layer Optional[str]

Optional source layer for vector tile sources.

None
filter_expression Optional[List]

Optional MapLibre filter expression.

None

Returns:

Type Description
Dict

The current queried features dict.

Examples:

>>> m.query_source_features("states-source")
>>> features = m.queried_features
Source code in anymap_ts/maplibre.py
def query_source_features(
    self,
    source_id: str,
    source_layer: Optional[str] = None,
    filter_expression: Optional[List] = None,
) -> Dict:
    """Query features from a source, including features not currently visible.

    Results are stored in the `queried_features` property.

    Args:
        source_id: The source to query.
        source_layer: Optional source layer for vector tile sources.
        filter_expression: Optional MapLibre filter expression.

    Returns:
        The current queried features dict.

    Example:
        >>> m.query_source_features("states-source")
        >>> features = m.queried_features
    """
    kwargs: Dict[str, Any] = {"sourceId": source_id}
    if source_layer is not None:
        kwargs["sourceLayer"] = source_layer
    if filter_expression is not None:
        kwargs["filter"] = filter_expression

    self.call_js_method("querySourceFeatures", **kwargs)
    return self._queried_features

remove_arc_layer(self, layer_id)

Remove an arc layer.

Parameters:

Name Type Description Default
layer_id str

Layer identifier to remove.

required
Source code in anymap_ts/maplibre.py
def remove_arc_layer(self, layer_id: str) -> None:
    """Remove an arc layer.

    Args:
        layer_id: Layer identifier to remove.
    """
    self._remove_layer_internal(layer_id, "removeArcLayer")

remove_cluster_layer(self, layer_id)

Remove a cluster layer and all its sublayers.

Parameters:

Name Type Description Default
layer_id str

Layer identifier to remove.

required
Source code in anymap_ts/maplibre.py
def remove_cluster_layer(self, layer_id: str) -> None:
    """Remove a cluster layer and all its sublayers.

    Args:
        layer_id: Layer identifier to remove.
    """
    self._remove_layer_internal(layer_id, "removeClusterLayer")

remove_cog_layer(self, layer_id)

Remove a COG layer.

Parameters:

Name Type Description Default
layer_id str

Layer identifier to remove.

required
Source code in anymap_ts/maplibre.py
def remove_cog_layer(self, layer_id: str) -> None:
    """Remove a COG layer.

    Args:
        layer_id: Layer identifier to remove.
    """
    self._remove_layer_internal(layer_id, "removeCOGLayer")

remove_colorbar(self, colorbar_id=None)

Remove a colorbar from the map.

Parameters:

Name Type Description Default
colorbar_id Optional[str]

Colorbar identifier to remove. If None, removes all colorbars.

None
Source code in anymap_ts/maplibre.py
def remove_colorbar(self, colorbar_id: Optional[str] = None) -> None:
    """Remove a colorbar from the map.

    Args:
        colorbar_id: Colorbar identifier to remove. If None, removes
            all colorbars.
    """
    if colorbar_id is None:
        cbar_keys = [k for k in self._controls.keys() if k.startswith("colorbar")]
        for key in cbar_keys:
            self.call_js_method("removeColorbar", colorbarId=key)
        self._controls = {
            k: v for k, v in self._controls.items() if not k.startswith("colorbar")
        }
    else:
        self.call_js_method("removeColorbar", colorbarId=colorbar_id)
        if colorbar_id in self._controls:
            controls = dict(self._controls)
            del controls[colorbar_id]
            self._controls = controls

remove_control(self, control_type)

Remove a map control.

Parameters:

Name Type Description Default
control_type str

Type of control to remove

required
Source code in anymap_ts/maplibre.py
def remove_control(self, control_type: str) -> None:
    """Remove a map control.

    Args:
        control_type: Type of control to remove
    """
    self.call_js_method("removeControl", control_type)
    if control_type in self._controls:
        controls = dict(self._controls)
        del controls[control_type]
        self._controls = controls

remove_coordinates_control(self)

Remove the coordinates display control.

Source code in anymap_ts/maplibre.py
def remove_coordinates_control(self) -> None:
    """Remove the coordinates display control."""
    self.call_js_method("removeCoordinatesControl")

remove_deck_layer(self, layer_id)

Remove a deck.gl layer from the map.

Parameters:

Name Type Description Default
layer_id str

Layer identifier to remove.

required
Source code in anymap_ts/maplibre.py
def remove_deck_layer(self, layer_id: str) -> None:
    """Remove a deck.gl layer from the map.

    Args:
        layer_id: Layer identifier to remove.
    """
    self._remove_layer_internal(layer_id, "removeDeckLayer")

remove_flatgeobuf(self, name)

Remove a FlatGeobuf layer from the map.

Parameters:

Name Type Description Default
name str

The layer identifier to remove.

required
Source code in anymap_ts/maplibre.py
def remove_flatgeobuf(self, name: str) -> None:
    """Remove a FlatGeobuf layer from the map.

    Args:
        name: The layer identifier to remove.
    """
    if name in self._layers:
        layers = dict(self._layers)
        del layers[name]
        self._layers = layers
    self._remove_from_layer_dict(name)
    self.call_js_method("removeFlatGeobuf", name=name)

remove_layer(self, layer_id)

Remove a layer from the map.

Parameters:

Name Type Description Default
layer_id str

Layer identifier to remove

required
Source code in anymap_ts/maplibre.py
def remove_layer(self, layer_id: str) -> None:
    """Remove a layer from the map.

    Args:
        layer_id: Layer identifier to remove
    """
    if layer_id in self._layers:
        layers = dict(self._layers)
        del layers[layer_id]
        self._layers = layers
    self._remove_from_layer_dict(layer_id)
    self.call_js_method("removeLayer", layer_id)

remove_legend(self, legend_id=None)

Remove a legend control from the map.

Parameters:

Name Type Description Default
legend_id Optional[str]

Legend identifier to remove. If None, removes all legends.

None
Source code in anymap_ts/maplibre.py
def remove_legend(self, legend_id: Optional[str] = None) -> None:
    """Remove a legend control from the map.

    Args:
        legend_id: Legend identifier to remove. If None, removes all legends.
    """
    if legend_id is None:
        # Remove all legends - create a copy of keys before iterating
        legend_keys = [k for k in self._controls.keys() if k.startswith("legend")]
        for key in legend_keys:
            self.call_js_method("removeLegend", key)
        # Rebuild controls dict without legend keys
        self._controls = {
            k: v for k, v in self._controls.items() if not k.startswith("legend")
        }
    else:
        self.call_js_method("removeLegend", legend_id)
        if legend_id in self._controls:
            controls = dict(self._controls)
            del controls[legend_id]
            self._controls = controls

remove_lidar_layer(self, layer_id=None)

Remove a LiDAR layer.

Parameters:

Name Type Description Default
layer_id Optional[str]

Layer identifier to remove. If None, removes all LiDAR layers.

None
Source code in anymap_ts/maplibre.py
def remove_lidar_layer(self, layer_id: Optional[str] = None) -> None:
    """Remove a LiDAR layer.

    Args:
        layer_id: Layer identifier to remove. If None, removes all LiDAR layers.
    """
    if layer_id:
        if layer_id in self._layers:
            layers = dict(self._layers)
            del layers[layer_id]
            self._layers = layers
        self.call_js_method("removeLidarLayer", id=layer_id)
    else:
        # Remove all lidar layers
        layers = dict(self._layers)
        self._layers = {k: v for k, v in layers.items() if v.get("type") != "lidar"}
        self.call_js_method("removeLidarLayer")

remove_marker(self, marker_id)

Remove a marker from the map.

Parameters:

Name Type Description Default
marker_id str

Marker identifier to remove.

required
Source code in anymap_ts/maplibre.py
def remove_marker(self, marker_id: str) -> None:
    """Remove a marker from the map.

    Args:
        marker_id: Marker identifier to remove.
    """
    self._remove_layer_internal(marker_id, "removeMarker")

remove_measure_control(self)

Remove the measurement control from the map.

Source code in anymap_ts/maplibre.py
def remove_measure_control(self) -> None:
    """Remove the measurement control from the map."""
    self.call_js_method("removeMeasureControl")
    if "measure-control" in self._controls:
        controls = dict(self._controls)
        del controls["measure-control"]
        self._controls = controls

remove_opacity_slider(self, layer_id)

Remove the opacity slider for a layer.

Parameters:

Name Type Description Default
layer_id str

Layer identifier.

required
Source code in anymap_ts/maplibre.py
def remove_opacity_slider(self, layer_id: str) -> None:
    """Remove the opacity slider for a layer.

    Args:
        layer_id: Layer identifier.
    """
    self.call_js_method("removeOpacitySlider", layerId=layer_id)

remove_pmtiles_layer(self, layer_id)

Remove a PMTiles layer.

Parameters:

Name Type Description Default
layer_id str

Layer identifier to remove.

required
Source code in anymap_ts/maplibre.py
def remove_pmtiles_layer(self, layer_id: str) -> None:
    """Remove a PMTiles layer.

    Args:
        layer_id: Layer identifier to remove.
    """
    self._remove_layer_internal(layer_id, "removePMTilesLayer")

remove_point_cloud_layer(self, layer_id)

Remove a point cloud layer.

Parameters:

Name Type Description Default
layer_id str

Layer identifier to remove.

required
Source code in anymap_ts/maplibre.py
def remove_point_cloud_layer(self, layer_id: str) -> None:
    """Remove a point cloud layer.

    Args:
        layer_id: Layer identifier to remove.
    """
    self._remove_layer_internal(layer_id, "removePointCloudLayer")

remove_print_control(self)

Remove the print/export control from the map.

Source code in anymap_ts/maplibre.py
def remove_print_control(self) -> None:
    """Remove the print/export control from the map."""
    self.call_js_method("removePrintControl")
    if "print-control" in self._controls:
        controls = dict(self._controls)
        del controls["print-control"]
        self._controls = controls

remove_search_control(self)

Remove the search/geocoder control from the map.

Source code in anymap_ts/maplibre.py
def remove_search_control(self) -> None:
    """Remove the search/geocoder control from the map."""
    self.call_js_method("removeSearchControl")
    if "search-control" in self._controls:
        controls = dict(self._controls)
        del controls["search-control"]
        self._controls = controls

remove_sky(self)

Remove sky and fog atmospheric effects from the map.

Examples:

>>> m.remove_sky()
Source code in anymap_ts/maplibre.py
def remove_sky(self) -> None:
    """Remove sky and fog atmospheric effects from the map.

    Example:
        >>> m.remove_sky()
    """
    self.call_js_method("removeSky")

remove_split_map(self)

Remove the split map comparison view.

Restores the map to normal single-view mode with all layers visible.

Source code in anymap_ts/maplibre.py
def remove_split_map(self) -> None:
    """Remove the split map comparison view.

    Restores the map to normal single-view mode with all layers visible.
    """
    self.call_js_method("removeSplitMap")

remove_style_switcher(self)

Remove the style switcher control.

Source code in anymap_ts/maplibre.py
def remove_style_switcher(self) -> None:
    """Remove the style switcher control."""
    self.call_js_method("removeStyleSwitcher")

remove_swipe_map(self)

Remove the swipe map comparison control.

Source code in anymap_ts/maplibre.py
def remove_swipe_map(self) -> None:
    """Remove the swipe map comparison control."""
    self.call_js_method("removeSwipeMap")

remove_time_slider(self)

Remove the time slider control.

Source code in anymap_ts/maplibre.py
def remove_time_slider(self) -> None:
    """Remove the time slider control."""
    self.call_js_method("removeTimeSlider")

remove_tooltip(self, layer_id)

Remove tooltip from a layer.

Parameters:

Name Type Description Default
layer_id str

The layer identifier.

required
Source code in anymap_ts/maplibre.py
def remove_tooltip(self, layer_id: str) -> None:
    """Remove tooltip from a layer.

    Args:
        layer_id: The layer identifier.
    """
    self.call_js_method("removeTooltip", layerId=layer_id)

remove_video_layer(self, name)

Remove a video layer from the map.

Parameters:

Name Type Description Default
name str

The layer identifier to remove.

required
Source code in anymap_ts/maplibre.py
def remove_video_layer(self, name: str) -> None:
    """Remove a video layer from the map.

    Args:
        name: The layer identifier to remove.
    """
    if name in self._layers:
        layers = dict(self._layers)
        del layers[name]
        self._layers = layers
    self._remove_from_layer_dict(name)
    self.call_js_method("removeVideoLayer", id=name)

remove_zarr_layer(self, layer_id)

Remove a Zarr layer.

Parameters:

Name Type Description Default
layer_id str

Layer identifier to remove.

required
Source code in anymap_ts/maplibre.py
def remove_zarr_layer(self, layer_id: str) -> None:
    """Remove a Zarr layer.

    Args:
        layer_id: Layer identifier to remove.
    """
    self._remove_layer_internal(layer_id, "removeZarrLayer")

resume_animation(self, animation_id)

Resume a paused animation.

Parameters:

Name Type Description Default
animation_id str

Animation identifier to resume.

required
Source code in anymap_ts/maplibre.py
def resume_animation(self, animation_id: str) -> None:
    """Resume a paused animation.

    Args:
        animation_id: Animation identifier to resume.
    """
    self.call_js_method("resumeAnimation", animation_id)

save_draw_data(self, filepath, driver=None)

Save drawn features to a file.

Parameters:

Name Type Description Default
filepath Union[str, Path]

Path to save file

required
driver Optional[str]

Output driver (auto-detected from extension if not provided)

None

Exceptions:

Type Description
ImportError

If geopandas is not installed

Source code in anymap_ts/maplibre.py
def save_draw_data(
    self,
    filepath: Union[str, Path],
    driver: Optional[str] = None,
) -> None:
    """Save drawn features to a file.

    Args:
        filepath: Path to save file
        driver: Output driver (auto-detected from extension if not provided)

    Raises:
        ImportError: If geopandas is not installed
    """
    try:
        import geopandas as gpd
    except ImportError:
        raise ImportError(
            "geopandas is required to save draw data. "
            "Install with: pip install anymap-ts[vector]"
        )

    data = self.get_draw_data()
    if not data.get("features"):
        print("No features to save")
        return

    gdf = gpd.GeoDataFrame.from_features(data["features"])
    filepath = Path(filepath)

    # Infer driver from extension
    if driver is None:
        ext = filepath.suffix.lower()
        driver_map = {
            ".geojson": "GeoJSON",
            ".json": "GeoJSON",
            ".shp": "ESRI Shapefile",
            ".gpkg": "GPKG",
        }
        driver = driver_map.get(ext, "GeoJSON")

    gdf.to_file(filepath, driver=driver)

seek_video(self, name, time)

Seek to a specific time in a video layer.

Parameters:

Name Type Description Default
name str

The video layer identifier.

required
time float

Time in seconds to seek to.

required
Source code in anymap_ts/maplibre.py
def seek_video(self, name: str, time: float) -> None:
    """Seek to a specific time in a video layer.

    Args:
        name: The video layer identifier.
        time: Time in seconds to seek to.
    """
    self.call_js_method("seekVideo", id=name, time=time)

set_animation_speed(self, animation_id, speed)

Set animation speed multiplier.

Parameters:

Name Type Description Default
animation_id str

Animation identifier.

required
speed float

Speed multiplier (1.0 = normal, 2.0 = double speed, etc.).

required
Source code in anymap_ts/maplibre.py
def set_animation_speed(self, animation_id: str, speed: float) -> None:
    """Set animation speed multiplier.

    Args:
        animation_id: Animation identifier.
        speed: Speed multiplier (1.0 = normal, 2.0 = double speed, etc.).
    """
    self.call_js_method("setAnimationSpeed", animation_id, speed)

set_filter(self, layer_id, filter_expression=None)

Set or clear a filter on a map layer.

Uses MapLibre GL JS filter expressions to show/hide features.

Parameters:

Name Type Description Default
layer_id str

The layer to apply the filter to.

required
filter_expression Optional[List]

A MapLibre filter expression (list). Pass None to clear the filter.

None

Examples:

>>> m.set_filter("states-layer", [">=", ["get", "density"], 100])
>>> m.set_filter("states-layer", None)  # Clear filter
Source code in anymap_ts/maplibre.py
def set_filter(
    self,
    layer_id: str,
    filter_expression: Optional[List] = None,
) -> None:
    """Set or clear a filter on a map layer.

    Uses MapLibre GL JS filter expressions to show/hide features.

    Args:
        layer_id: The layer to apply the filter to.
        filter_expression: A MapLibre filter expression (list).
            Pass None to clear the filter.

    Example:
        >>> m.set_filter("states-layer", [">=", ["get", "density"], 100])
        >>> m.set_filter("states-layer", None)  # Clear filter
    """
    self.call_js_method(
        "setFilter",
        layerId=layer_id,
        filter=filter_expression,
    )

set_layout_property(self, layer_id, property_name, value)

Set a layout property for a layer.

Parameters:

Name Type Description Default
layer_id str

Layer identifier.

required
property_name str

Name of the layout property (e.g., 'visibility').

required
value Any

New value for the property.

required

Examples:

>>> m.set_layout_property("my-layer", "visibility", "none")
Source code in anymap_ts/maplibre.py
def set_layout_property(
    self, layer_id: str, property_name: str, value: Any
) -> None:
    """Set a layout property for a layer.

    Args:
        layer_id: Layer identifier.
        property_name: Name of the layout property (e.g., 'visibility').
        value: New value for the property.

    Example:
        >>> m.set_layout_property("my-layer", "visibility", "none")
    """
    self.call_js_method("setLayoutProperty", layer_id, property_name, value)

set_lidar_color_scheme(self, color_scheme)

Set the LiDAR color scheme.

Parameters:

Name Type Description Default
color_scheme str

Color scheme ('elevation', 'intensity', 'classification', 'rgb').

required
Source code in anymap_ts/maplibre.py
def set_lidar_color_scheme(self, color_scheme: str) -> None:
    """Set the LiDAR color scheme.

    Args:
        color_scheme: Color scheme ('elevation', 'intensity', 'classification', 'rgb').
    """
    self.call_js_method("setLidarColorScheme", colorScheme=color_scheme)

set_lidar_opacity(self, opacity)

Set the LiDAR layer opacity.

Parameters:

Name Type Description Default
opacity float

Opacity value between 0 and 1.

required
Source code in anymap_ts/maplibre.py
def set_lidar_opacity(self, opacity: float) -> None:
    """Set the LiDAR layer opacity.

    Args:
        opacity: Opacity value between 0 and 1.
    """
    self.call_js_method("setLidarOpacity", opacity=opacity)

set_lidar_point_size(self, point_size)

Set the LiDAR point size.

Parameters:

Name Type Description Default
point_size float

Point size in pixels.

required
Source code in anymap_ts/maplibre.py
def set_lidar_point_size(self, point_size: float) -> None:
    """Set the LiDAR point size.

    Args:
        point_size: Point size in pixels.
    """
    self.call_js_method("setLidarPointSize", pointSize=point_size)

set_opacity(self, layer_id, opacity)

Set layer opacity.

Parameters:

Name Type Description Default
layer_id str

Layer identifier

required
opacity float

Opacity value between 0 and 1

required
Source code in anymap_ts/maplibre.py
def set_opacity(self, layer_id: str, opacity: float) -> None:
    """Set layer opacity.

    Args:
        layer_id: Layer identifier
        opacity: Opacity value between 0 and 1
    """
    self._validate_opacity(opacity)
    self.call_js_method("setOpacity", layer_id, opacity)

set_paint_property(self, layer_id, property_name, value)

Set a paint property for a layer.

Parameters:

Name Type Description Default
layer_id str

Layer identifier.

required
property_name str

Name of the paint property (e.g., 'fill-color').

required
value Any

New value for the property.

required

Examples:

>>> m.set_paint_property("my-layer", "fill-color", "#ff0000")
>>> m.set_paint_property("my-layer", "fill-opacity", 0.5)
Source code in anymap_ts/maplibre.py
def set_paint_property(self, layer_id: str, property_name: str, value: Any) -> None:
    """Set a paint property for a layer.

    Args:
        layer_id: Layer identifier.
        property_name: Name of the paint property (e.g., 'fill-color').
        value: New value for the property.

    Example:
        >>> m.set_paint_property("my-layer", "fill-color", "#ff0000")
        >>> m.set_paint_property("my-layer", "fill-opacity", 0.5)
    """
    self.call_js_method("setPaintProperty", layer_id, property_name, value)

set_projection(self, projection='mercator')

Set the map projection.

MapLibre GL JS v4+ supports globe projection for a 3D globe view.

Parameters:

Name Type Description Default
projection str

Projection type. Supported values: 'mercator', 'globe'.

'mercator'

Examples:

>>> m = MapLibreMap()
>>> m.set_projection("globe")
Source code in anymap_ts/maplibre.py
def set_projection(self, projection: str = "mercator") -> None:
    """Set the map projection.

    MapLibre GL JS v4+ supports globe projection for a 3D globe view.

    Args:
        projection: Projection type. Supported values: 'mercator', 'globe'.

    Example:
        >>> m = MapLibreMap()
        >>> m.set_projection("globe")
    """
    self.call_js_method("setProjection", projection=projection)

set_sky(self, sky_color='#88C6FC', horizon_color='#F0E4D4', fog_color='#FFFFFF', sky_horizon_blend=0.5, horizon_fog_blend=0.5, fog_ground_blend=0.5, atmosphere_blend=0.8, **kwargs)

Set sky and fog atmospheric effects for 3D terrain visualization.

MapLibre v5 unifies sky and fog into a single map.setSky() API. Best used with 3D terrain enabled.

Parameters:

Name Type Description Default
sky_color str

Color of the sky. Default is "#88C6FC".

'#88C6FC'
horizon_color str

Color at the horizon. Default is "#F0E4D4".

'#F0E4D4'
fog_color str

Color of the fog. Default is "#FFFFFF".

'#FFFFFF'
sky_horizon_blend float

Blend between sky and horizon (0-1). Default is 0.5.

0.5
horizon_fog_blend float

Blend between horizon and fog (0-1). Default is 0.5.

0.5
fog_ground_blend float

Blend between fog and ground (0-1). Default is 0.5.

0.5
atmosphere_blend float

Intensity of the atmosphere effect (0-1). Default is 0.8.

0.8
**kwargs

Additional sky options.

{}

Examples:

>>> from anymap_ts import Map
>>> m = Map(center=[-122.4, 37.8], zoom=12, pitch=60)
>>> m.add_3d_terrain(exaggeration=1.5)
>>> m.set_sky()
Source code in anymap_ts/maplibre.py
def set_sky(
    self,
    sky_color: str = "#88C6FC",
    horizon_color: str = "#F0E4D4",
    fog_color: str = "#FFFFFF",
    sky_horizon_blend: float = 0.5,
    horizon_fog_blend: float = 0.5,
    fog_ground_blend: float = 0.5,
    atmosphere_blend: float = 0.8,
    **kwargs,
) -> None:
    """Set sky and fog atmospheric effects for 3D terrain visualization.

    MapLibre v5 unifies sky and fog into a single `map.setSky()` API.
    Best used with 3D terrain enabled.

    Args:
        sky_color: Color of the sky. Default is "#88C6FC".
        horizon_color: Color at the horizon. Default is "#F0E4D4".
        fog_color: Color of the fog. Default is "#FFFFFF".
        sky_horizon_blend: Blend between sky and horizon (0-1).
            Default is 0.5.
        horizon_fog_blend: Blend between horizon and fog (0-1).
            Default is 0.5.
        fog_ground_blend: Blend between fog and ground (0-1).
            Default is 0.5.
        atmosphere_blend: Intensity of the atmosphere effect (0-1).
            Default is 0.8.
        **kwargs: Additional sky options.

    Example:
        >>> from anymap_ts import Map
        >>> m = Map(center=[-122.4, 37.8], zoom=12, pitch=60)
        >>> m.add_3d_terrain(exaggeration=1.5)
        >>> m.set_sky()
    """
    self.call_js_method(
        "setSky",
        skyColor=sky_color,
        horizonColor=horizon_color,
        fogColor=fog_color,
        skyHorizonBlend=sky_horizon_blend,
        horizonFogBlend=horizon_fog_blend,
        fogGroundBlend=fog_ground_blend,
        atmosphereBlend=atmosphere_blend,
        **kwargs,
    )

set_visibility(self, layer_id, visible)

Set layer visibility.

Parameters:

Name Type Description Default
layer_id str

Layer identifier

required
visible bool

Whether layer should be visible

required
Source code in anymap_ts/maplibre.py
def set_visibility(self, layer_id: str, visible: bool) -> None:
    """Set layer visibility.

    Args:
        layer_id: Layer identifier
        visible: Whether layer should be visible
    """
    self.call_js_method("setVisibility", layer_id, visible)

stop_animation(self, animation_id)

Stop a running animation.

Parameters:

Name Type Description Default
animation_id str

Animation identifier to stop.

required
Source code in anymap_ts/maplibre.py
def stop_animation(self, animation_id: str) -> None:
    """Stop a running animation.

    Args:
        animation_id: Animation identifier to stop.
    """
    self.call_js_method("stopAnimation", animation_id)
    if animation_id in self._layers:
        layers = dict(self._layers)
        del layers[animation_id]
        self._layers = layers

to_geojson(self, layer_id=None)

Get layer data as GeoJSON.

This triggers a query to the JavaScript side. The result is returned asynchronously via the _queried_features trait.

On the first call with a layer_id, the query is sent and None is returned. Run this method in one notebook cell, then call to_geojson() (without arguments) in the next cell to read the result.

Parameters:

Name Type Description Default
layer_id Optional[str]

Source/layer ID to export. If None, returns previously queried features.

None

Returns:

Type Description
Optional[Dict]

GeoJSON FeatureCollection dict, or None if not yet available.

Examples:

>>> # Cell 1 – trigger the query
>>> m.to_geojson("my-data")
>>> # Cell 2 – read the result
>>> result = m.to_geojson()
Source code in anymap_ts/maplibre.py
def to_geojson(self, layer_id: Optional[str] = None) -> Optional[Dict]:
    """Get layer data as GeoJSON.

    This triggers a query to the JavaScript side. The result is
    returned asynchronously via the ``_queried_features`` trait.

    On the first call with a ``layer_id``, the query is sent and
    ``None`` is returned. Run this method in one notebook cell,
    then call ``to_geojson()`` (without arguments) in the next cell
    to read the result.

    Args:
        layer_id: Source/layer ID to export. If ``None``, returns
            previously queried features.

    Returns:
        GeoJSON FeatureCollection dict, or ``None`` if not yet
        available.

    Example:
        >>> # Cell 1 – trigger the query
        >>> m.to_geojson("my-data")
        >>> # Cell 2 – read the result
        >>> result = m.to_geojson()
    """
    if layer_id:
        self.call_js_method("getLayerData", sourceId=layer_id)
    features = self._queried_features
    if features and "data" in features:
        return features["data"]
    return None

to_geopandas(self, layer_id=None)

Get layer data as a GeoDataFrame.

Requires geopandas to be installed. Works the same as :meth:to_geojson – trigger with a layer_id in one cell, then call to_geopandas() in the next cell.

Parameters:

Name Type Description Default
layer_id Optional[str]

Source/layer ID to export. If None, returns previously queried features.

None

Returns:

Type Description
Any

GeoDataFrame, or None if data not available.

Examples:

>>> # Cell 1 – trigger the query
>>> m.to_geojson("my-data")
>>> # Cell 2 – read the result
>>> gdf = m.to_geopandas()
Source code in anymap_ts/maplibre.py
def to_geopandas(self, layer_id: Optional[str] = None) -> Any:
    """Get layer data as a GeoDataFrame.

    Requires geopandas to be installed. Works the same as
    :meth:`to_geojson` – trigger with a ``layer_id`` in one cell,
    then call ``to_geopandas()`` in the next cell.

    Args:
        layer_id: Source/layer ID to export. If ``None``, returns
            previously queried features.

    Returns:
        GeoDataFrame, or ``None`` if data not available.

    Example:
        >>> # Cell 1 – trigger the query
        >>> m.to_geojson("my-data")
        >>> # Cell 2 – read the result
        >>> gdf = m.to_geopandas()
    """
    geojson = self.to_geojson(layer_id)
    if geojson is None:
        return None
    try:
        import geopandas as gpd

        return gpd.GeoDataFrame.from_features(geojson.get("features", []))
    except ImportError:
        raise ImportError("geopandas is required for to_geopandas()")

update_colorbar(self, colorbar_id=None, **kwargs)

Update an existing colorbar's properties.

Parameters:

Name Type Description Default
colorbar_id Optional[str]

Colorbar identifier to update. If None, updates the first colorbar found.

None
**kwargs

Properties to update (colormap, vmin, vmax, label, units, orientation, bar_thickness, bar_length, ticks, opacity).

{}
Source code in anymap_ts/maplibre.py
def update_colorbar(self, colorbar_id: Optional[str] = None, **kwargs) -> None:
    """Update an existing colorbar's properties.

    Args:
        colorbar_id: Colorbar identifier to update. If None, updates
            the first colorbar found.
        **kwargs: Properties to update (colormap, vmin, vmax, label,
            units, orientation, bar_thickness, bar_length, ticks, opacity).
    """
    if colorbar_id is None:
        cbar_keys = [k for k in self._controls.keys() if k.startswith("colorbar")]
        if not cbar_keys:
            raise ValueError("No colorbar found to update")
        colorbar_id = cbar_keys[0]

    if colorbar_id not in self._controls:
        raise ValueError(f"Colorbar '{colorbar_id}' not found")

    js_kwargs: Dict[str, Any] = {"colorbarId": colorbar_id}
    key_map = {
        "bar_thickness": "barThickness",
        "bar_length": "barLength",
    }
    for key, value in kwargs.items():
        js_key = key_map.get(key, key)
        js_kwargs[js_key] = value

    self.call_js_method("updateColorbar", **js_kwargs)

    for key, value in kwargs.items():
        if key in self._controls.get(colorbar_id, {}):
            self._controls[colorbar_id][key] = value

update_geojson_source(self, source_id, data)

Update the data of an existing GeoJSON source in place.

This enables real-time/streaming data updates without removing and re-adding layers. Critical for live dashboards.

Parameters:

Name Type Description Default
source_id str

The ID of the GeoJSON source to update.

required
data Any

New GeoJSON data (dict, GeoDataFrame, or URL string).

required

Examples:

>>> m = MapLibreMap()
>>> m.add_geojson("initial.geojson", name="points")
>>> # Later, update with new data
>>> m.update_geojson_source("points", new_geojson_data)
Source code in anymap_ts/maplibre.py
def update_geojson_source(self, source_id: str, data: Any) -> None:
    """Update the data of an existing GeoJSON source in place.

    This enables real-time/streaming data updates without removing
    and re-adding layers. Critical for live dashboards.

    Args:
        source_id: The ID of the GeoJSON source to update.
        data: New GeoJSON data (dict, GeoDataFrame, or URL string).

    Example:
        >>> m = MapLibreMap()
        >>> m.add_geojson("initial.geojson", name="points")
        >>> # Later, update with new data
        >>> m.update_geojson_source("points", new_geojson_data)
    """
    processed_data = self._process_deck_data(data)
    self.call_js_method(
        "updateGeoJSONSource",
        sourceId=source_id,
        data=processed_data,
    )

update_legend(self, legend_id, title=None, labels=None, colors=None, opacity=None, **kwargs)

Update an existing legend's properties.

Parameters:

Name Type Description Default
legend_id str

Legend identifier to update

required
title Optional[str]

New title (if provided)

None
labels Optional[List[str]]

New labels list (if provided)

None
colors Optional[List[str]]

New colors list (if provided)

None
opacity Optional[float]

New opacity (if provided)

None
**kwargs

Additional properties to update

{}
Source code in anymap_ts/maplibre.py
def update_legend(
    self,
    legend_id: str,
    title: Optional[str] = None,
    labels: Optional[List[str]] = None,
    colors: Optional[List[str]] = None,
    opacity: Optional[float] = None,
    **kwargs,
) -> None:
    """Update an existing legend's properties.

    Args:
        legend_id: Legend identifier to update
        title: New title (if provided)
        labels: New labels list (if provided)
        colors: New colors list (if provided)
        opacity: New opacity (if provided)
        **kwargs: Additional properties to update
    """
    if legend_id not in self._controls:
        raise ValueError(f"Legend '{legend_id}' not found")

    update_params = {"id": legend_id}

    if title is not None:
        update_params["title"] = title
        self._controls[legend_id]["title"] = title

    if labels is not None and colors is not None:
        if len(labels) != len(colors):
            raise ValueError("Number of labels must match number of colors")

        legend_items = [
            {"label": label, "color": color} for label, color in zip(labels, colors)
        ]
        update_params["items"] = legend_items
        self._controls[legend_id]["labels"] = labels
        self._controls[legend_id]["colors"] = colors

    elif labels is not None or colors is not None:
        raise ValueError("Both labels and colors must be provided together")

    if opacity is not None:
        update_params["opacity"] = opacity
        self._controls[legend_id]["opacity"] = opacity

    update_params.update(kwargs)
    self.call_js_method("updateLegend", **update_params)

update_zarr_layer(self, layer_id, selector=None, clim=None, colormap=None, opacity=None)

Update a Zarr layer's properties dynamically.

Parameters:

Name Type Description Default
layer_id str

Layer identifier.

required
selector Optional[Dict[str, Any]]

New dimension selector.

None
clim Optional[Tuple[float, float]]

New color range.

None
colormap Optional[List[str]]

New colormap.

None
opacity Optional[float]

New opacity value (0-1).

None
Source code in anymap_ts/maplibre.py
def update_zarr_layer(
    self,
    layer_id: str,
    selector: Optional[Dict[str, Any]] = None,
    clim: Optional[Tuple[float, float]] = None,
    colormap: Optional[List[str]] = None,
    opacity: Optional[float] = None,
) -> None:
    """Update a Zarr layer's properties dynamically.

    Args:
        layer_id: Layer identifier.
        selector: New dimension selector.
        clim: New color range.
        colormap: New colormap.
        opacity: New opacity value (0-1).
    """
    update_kwargs: Dict[str, Any] = {"id": layer_id}
    if selector is not None:
        update_kwargs["selector"] = selector
    if clim is not None:
        update_kwargs["clim"] = list(clim)
    if colormap is not None:
        update_kwargs["colormap"] = colormap
    if opacity is not None:
        update_kwargs["opacity"] = opacity
    self.call_js_method("updateZarrLayer", **update_kwargs)

openlayers

OpenLayers map widget implementation.

OpenLayersMap (MapWidget)

Interactive map widget using OpenLayers.

This class provides a Python interface to OpenLayers maps with full bidirectional communication through anywidget. OpenLayers excels at WMS/WMTS support and projection handling.

Examples:

>>> from anymap_ts import OpenLayersMap
>>> m = OpenLayersMap(center=[-122.4, 37.8], zoom=10)
>>> m.add_basemap("OpenStreetMap")
>>> m.add_wms_layer(
...     url="https://example.com/wms",
...     layers="layer_name",
...     name="WMS Layer"
... )
>>> m
Source code in anymap_ts/openlayers.py
class OpenLayersMap(MapWidget):
    """Interactive map widget using OpenLayers.

    This class provides a Python interface to OpenLayers maps with
    full bidirectional communication through anywidget. OpenLayers
    excels at WMS/WMTS support and projection handling.

    Example:
        >>> from anymap_ts import OpenLayersMap
        >>> m = OpenLayersMap(center=[-122.4, 37.8], zoom=10)
        >>> m.add_basemap("OpenStreetMap")
        >>> m.add_wms_layer(
        ...     url="https://example.com/wms",
        ...     layers="layer_name",
        ...     name="WMS Layer"
        ... )
        >>> m
    """

    # ESM module and CSS for frontend
    _esm = STATIC_DIR / "openlayers.js"
    _css = STATIC_DIR / "openlayers.css"

    # OpenLayers-specific traits
    projection = traitlets.Unicode("EPSG:3857").tag(sync=True)
    rotation = traitlets.Float(0.0).tag(sync=True)

    # Layer tracking
    _layer_dict = traitlets.Dict({}).tag(sync=True)

    def __init__(
        self,
        center: Tuple[float, float] = (0.0, 0.0),
        zoom: float = 2.0,
        width: str = "100%",
        height: str = "600px",
        projection: str = "EPSG:3857",
        rotation: float = 0.0,
        controls: Optional[Dict[str, Any]] = None,
        **kwargs,
    ):
        """Initialize an OpenLayers map.

        Args:
            center: Map center as (longitude, latitude).
            zoom: Initial zoom level.
            width: Map width as CSS string.
            height: Map height as CSS string.
            projection: Map projection (default EPSG:3857).
            rotation: Map rotation in radians.
            controls: Dict of controls to add.
            **kwargs: Additional widget arguments.
        """
        super().__init__(
            center=list(center),
            zoom=zoom,
            width=width,
            height=height,
            projection=projection,
            rotation=rotation,
            **kwargs,
        )

        # Initialize layer dictionary
        self._layer_dict = {"Background": []}

        # Add default controls
        if controls is None:
            controls = {"zoom": True, "attribution": True}

        for control_name, config in controls.items():
            if config:
                self.add_control(
                    control_name, **(config if isinstance(config, dict) else {})
                )

    # -------------------------------------------------------------------------
    # Basemap Methods
    # -------------------------------------------------------------------------

    def add_basemap(
        self,
        basemap: str = "OpenStreetMap",
        attribution: Optional[str] = None,
        **kwargs,
    ) -> None:
        """Add a basemap layer.

        Args:
            basemap: Name of basemap provider (e.g., "OpenStreetMap", "CartoDB.Positron").
            attribution: Custom attribution text.
            **kwargs: Additional options.
        """
        url, default_attribution = get_basemap_url(basemap)
        self.call_js_method(
            "addBasemap",
            url,
            attribution=attribution or default_attribution,
            name=basemap,
            **kwargs,
        )

        basemaps = self._layer_dict.get("Basemaps", [])
        if basemap not in basemaps:
            self._layer_dict = {
                **self._layer_dict,
                "Basemaps": basemaps + [basemap],
            }

    # -------------------------------------------------------------------------
    # Tile Layer Methods
    # -------------------------------------------------------------------------

    def add_tile_layer(
        self,
        url: str,
        name: Optional[str] = None,
        attribution: str = "",
        min_zoom: int = 0,
        max_zoom: int = 22,
        opacity: float = 1.0,
        **kwargs,
    ) -> None:
        """Add an XYZ tile layer.

        Args:
            url: Tile URL template with {x}, {y}, {z} placeholders.
            name: Layer name.
            attribution: Attribution text.
            min_zoom: Minimum zoom level.
            max_zoom: Maximum zoom level.
            opacity: Layer opacity.
            **kwargs: Additional options.
        """
        layer_id = name or f"tiles-{len(self._layers)}"

        self.call_js_method(
            "addTileLayer",
            url,
            name=layer_id,
            attribution=attribution,
            minZoom=min_zoom,
            maxZoom=max_zoom,
            opacity=opacity,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {"id": layer_id, "type": "tile"},
        }

    # -------------------------------------------------------------------------
    # Vector Data Methods
    # -------------------------------------------------------------------------

    def add_vector(
        self,
        data: Any,
        name: Optional[str] = None,
        style: Optional[Dict] = None,
        fit_bounds: bool = True,
        **kwargs,
    ) -> None:
        """Add vector data to the map.

        Args:
            data: GeoJSON dict, GeoDataFrame, or path to vector file.
            name: Layer name.
            style: Style configuration dict.
            fit_bounds: Whether to fit map to data bounds.
            **kwargs: Additional layer options.
        """
        geojson = to_geojson(data)
        layer_id = name or f"vector-{len(self._layers)}"

        if style is None:
            style = self._get_default_style(geojson)

        self.call_js_method(
            "addGeoJSON",
            data=geojson,
            name=layer_id,
            style=style,
            fitBounds=fit_bounds,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {"id": layer_id, "type": "vector"},
        }

    def add_geojson(
        self,
        data: Union[str, Dict],
        name: Optional[str] = None,
        style: Optional[Dict] = None,
        fit_bounds: bool = True,
        **kwargs,
    ) -> None:
        """Add GeoJSON data to the map.

        Args:
            data: GeoJSON dict or URL to GeoJSON file.
            name: Layer name.
            style: Style configuration dict.
            fit_bounds: Whether to fit map to data bounds.
            **kwargs: Additional layer options.
        """
        self.add_vector(
            data,
            name=name,
            style=style,
            fit_bounds=fit_bounds,
            **kwargs,
        )

    def _get_default_style(self, geojson: Dict) -> Dict:
        """Get default style based on geometry type.

        Args:
            geojson: GeoJSON data.

        Returns:
            Style configuration dict.
        """
        geom_type = self._infer_geom_type(geojson)

        if geom_type in ["Point", "MultiPoint"]:
            return {
                "fillColor": "rgba(51, 136, 255, 0.8)",
                "strokeColor": "#ffffff",
                "strokeWidth": 2,
                "radius": 6,
            }
        elif geom_type in ["LineString", "MultiLineString"]:
            return {
                "strokeColor": "#3388ff",
                "strokeWidth": 3,
            }
        else:  # Polygon, MultiPolygon
            return {
                "fillColor": "rgba(51, 136, 255, 0.5)",
                "strokeColor": "#3388ff",
                "strokeWidth": 2,
            }

    def _infer_geom_type(self, geojson: Dict) -> str:
        """Infer geometry type from GeoJSON.

        Args:
            geojson: GeoJSON data.

        Returns:
            Geometry type string.
        """
        if geojson.get("type") == "FeatureCollection":
            features = geojson.get("features", [])
            if features:
                return features[0].get("geometry", {}).get("type", "Point")
        elif geojson.get("type") == "Feature":
            return geojson.get("geometry", {}).get("type", "Point")
        return "Point"

    # -------------------------------------------------------------------------
    # WMS/WMTS Methods
    # -------------------------------------------------------------------------

    def add_wms_layer(
        self,
        url: str,
        layers: str,
        name: Optional[str] = None,
        format: str = "image/png",
        transparent: bool = True,
        server_type: Optional[str] = None,
        attribution: str = "",
        **kwargs,
    ) -> None:
        """Add a WMS tile layer.

        Args:
            url: WMS service URL.
            layers: Comma-separated layer names.
            name: Layer name for the map.
            format: Image format (default: image/png).
            transparent: Whether to request transparent images.
            server_type: Server type ('mapserver', 'geoserver', 'qgis').
            attribution: Attribution text.
            **kwargs: Additional WMS parameters.
        """
        layer_id = name or f"wms-{len(self._layers)}"

        self.call_js_method(
            "addWMSLayer",
            url=url,
            layers=layers,
            name=layer_id,
            format=format,
            transparent=transparent,
            serverType=server_type,
            attribution=attribution,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {"id": layer_id, "type": "wms"},
        }

    def add_image_wms_layer(
        self,
        url: str,
        layers: str,
        name: Optional[str] = None,
        format: str = "image/png",
        transparent: bool = True,
        server_type: Optional[str] = None,
        attribution: str = "",
        **kwargs,
    ) -> None:
        """Add a single-image WMS layer (not tiled).

        Args:
            url: WMS service URL.
            layers: Comma-separated layer names.
            name: Layer name for the map.
            format: Image format (default: image/png).
            transparent: Whether to request transparent images.
            server_type: Server type ('mapserver', 'geoserver', 'qgis').
            attribution: Attribution text.
            **kwargs: Additional WMS parameters.
        """
        layer_id = name or f"imagewms-{len(self._layers)}"

        self.call_js_method(
            "addImageWMSLayer",
            url=url,
            layers=layers,
            name=layer_id,
            format=format,
            transparent=transparent,
            serverType=server_type,
            attribution=attribution,
            **kwargs,
        )

        self._layers = {
            **self._layers,
            layer_id: {"id": layer_id, "type": "imagewms"},
        }

    # -------------------------------------------------------------------------
    # Layer Management
    # -------------------------------------------------------------------------

    def remove_layer(self, layer_id: str) -> None:
        """Remove a layer from the map.

        Args:
            layer_id: Layer identifier to remove.
        """
        if layer_id in self._layers:
            layers = dict(self._layers)
            del layers[layer_id]
            self._layers = layers
        self.call_js_method("removeLayer", layer_id)

    def set_visibility(self, layer_id: str, visible: bool) -> None:
        """Set layer visibility.

        Args:
            layer_id: Layer identifier.
            visible: Whether layer should be visible.
        """
        self.call_js_method("setVisibility", layer_id, visible)

    def set_opacity(self, layer_id: str, opacity: float) -> None:
        """Set layer opacity.

        Args:
            layer_id: Layer identifier.
            opacity: Opacity value between 0 and 1.
        """
        self.call_js_method("setOpacity", layer_id, opacity)

    # -------------------------------------------------------------------------
    # Controls
    # -------------------------------------------------------------------------

    def add_control(
        self,
        control_type: str,
        position: str = "top-right",
        **kwargs,
    ) -> None:
        """Add a map control.

        Args:
            control_type: Type of control ('zoom', 'scale', 'fullscreen', etc.).
            position: Control position.
            **kwargs: Control-specific options.
        """
        self.call_js_method("addControl", control_type, position=position, **kwargs)
        self._controls = {
            **self._controls,
            control_type: {"type": control_type, "position": position, **kwargs},
        }

    def remove_control(self, control_type: str) -> None:
        """Remove a map control.

        Args:
            control_type: Type of control to remove.
        """
        self.call_js_method("removeControl", control_type)
        if control_type in self._controls:
            controls = dict(self._controls)
            del controls[control_type]
            self._controls = controls

    # -------------------------------------------------------------------------
    # Navigation
    # -------------------------------------------------------------------------

    def set_center(self, lng: float, lat: float) -> None:
        """Set the map center.

        Args:
            lng: Longitude.
            lat: Latitude.
        """
        self.center = [lng, lat]
        self.call_js_method("setCenter", lng, lat)

    def set_zoom(self, zoom: float) -> None:
        """Set the map zoom level.

        Args:
            zoom: Zoom level.
        """
        self.zoom = zoom
        self.call_js_method("setZoom", zoom)

    def fly_to(
        self,
        lng: float,
        lat: float,
        zoom: Optional[float] = None,
        duration: int = 2000,
    ) -> None:
        """Animate to a new location.

        Args:
            lng: Target longitude.
            lat: Target latitude.
            zoom: Target zoom level (optional).
            duration: Animation duration in milliseconds.
        """
        self.call_js_method(
            "flyTo", lng, lat, zoom=zoom or self.zoom, duration=duration
        )

    def fit_bounds(
        self,
        bounds: List[float],
        padding: int = 50,
        duration: int = 1000,
    ) -> None:
        """Fit the map to bounds.

        Args:
            bounds: Bounds as [minLng, minLat, maxLng, maxLat].
            padding: Padding in pixels.
            duration: Animation duration in milliseconds.
        """
        self.call_js_method("fitBounds", bounds, padding=padding, duration=duration)

    def fit_extent(
        self,
        extent: List[float],
        padding: int = 50,
        duration: int = 1000,
    ) -> None:
        """Fit the map to an extent (in map projection).

        Args:
            extent: Extent as [minX, minY, maxX, maxY] in map projection.
            padding: Padding in pixels.
            duration: Animation duration in milliseconds.
        """
        self.call_js_method("fitExtent", extent, padding=padding, duration=duration)

    # -------------------------------------------------------------------------
    # Markers
    # -------------------------------------------------------------------------

    def add_marker(
        self,
        lng: float,
        lat: float,
        popup: Optional[str] = None,
        color: str = "#3388ff",
        name: Optional[str] = None,
        **kwargs,
    ) -> None:
        """Add a marker to the map.

        Args:
            lng: Marker longitude.
            lat: Marker latitude.
            popup: Popup content (HTML string).
            color: Marker color.
            name: Marker identifier.
            **kwargs: Additional options.
        """
        marker_id = name or f"marker-{len(self._layers)}"
        self.call_js_method(
            "addMarker",
            lng,
            lat,
            popup=popup,
            color=color,
            id=marker_id,
            **kwargs,
        )

    # -------------------------------------------------------------------------
    # HTML Export
    # -------------------------------------------------------------------------

    def _generate_html_template(self) -> str:
        """Generate standalone HTML for the map."""
        template_path = Path(__file__).parent / "templates" / "openlayers.html"

        if template_path.exists():
            template = template_path.read_text(encoding="utf-8")
        else:
            template = self._get_default_template()

        state = {
            "center": self.center,
            "zoom": self.zoom,
            "projection": self.projection,
            "rotation": self.rotation,
            "width": self.width,
            "height": self.height,
            "layers": self._layers,
            "controls": self._controls,
            "js_calls": self._js_calls,
        }

        template = template.replace("{{state}}", json.dumps(state, indent=2))
        return template

    def _get_default_template(self) -> str:
        """Get default HTML template."""
        return """<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>OpenLayers Map</title>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ol@v10.0.0/ol.css">
    <script src="https://cdn.jsdelivr.net/npm/ol@v10.0.0/dist/ol.js"></script>
    <style>
        * { margin: 0; padding: 0; box-sizing: border-box; }
        html, body { height: 100%; }
        #map { position: absolute; top: 0; bottom: 0; width: 100%; }
    </style>
</head>
<body>
    <div id="map"></div>
    <script>
        const state = {{state}};

        const map = new ol.Map({
            target: 'map',
            view: new ol.View({
                center: ol.proj.fromLonLat(state.center),
                zoom: state.zoom
            })
        });

        for (const call of state.js_calls || []) {
            executeMethod(call.method, call.args, call.kwargs);
        }

        function executeMethod(method, args, kwargs) {
            console.log('Executing:', method, args, kwargs);
        }
    </script>
</body>
</html>"""

__init__(self, center=(0.0, 0.0), zoom=2.0, width='100%', height='600px', projection='EPSG:3857', rotation=0.0, controls=None, **kwargs) special

Initialize an OpenLayers map.

Parameters:

Name Type Description Default
center Tuple[float, float]

Map center as (longitude, latitude).

(0.0, 0.0)
zoom float

Initial zoom level.

2.0
width str

Map width as CSS string.

'100%'
height str

Map height as CSS string.

'600px'
projection str

Map projection (default EPSG:3857).

'EPSG:3857'
rotation float

Map rotation in radians.

0.0
controls Optional[Dict[str, Any]]

Dict of controls to add.

None
**kwargs

Additional widget arguments.

{}
Source code in anymap_ts/openlayers.py
def __init__(
    self,
    center: Tuple[float, float] = (0.0, 0.0),
    zoom: float = 2.0,
    width: str = "100%",
    height: str = "600px",
    projection: str = "EPSG:3857",
    rotation: float = 0.0,
    controls: Optional[Dict[str, Any]] = None,
    **kwargs,
):
    """Initialize an OpenLayers map.

    Args:
        center: Map center as (longitude, latitude).
        zoom: Initial zoom level.
        width: Map width as CSS string.
        height: Map height as CSS string.
        projection: Map projection (default EPSG:3857).
        rotation: Map rotation in radians.
        controls: Dict of controls to add.
        **kwargs: Additional widget arguments.
    """
    super().__init__(
        center=list(center),
        zoom=zoom,
        width=width,
        height=height,
        projection=projection,
        rotation=rotation,
        **kwargs,
    )

    # Initialize layer dictionary
    self._layer_dict = {"Background": []}

    # Add default controls
    if controls is None:
        controls = {"zoom": True, "attribution": True}

    for control_name, config in controls.items():
        if config:
            self.add_control(
                control_name, **(config if isinstance(config, dict) else {})
            )

add_basemap(self, basemap='OpenStreetMap', attribution=None, **kwargs)

Add a basemap layer.

Parameters:

Name Type Description Default
basemap str

Name of basemap provider (e.g., "OpenStreetMap", "CartoDB.Positron").

'OpenStreetMap'
attribution Optional[str]

Custom attribution text.

None
**kwargs

Additional options.

{}
Source code in anymap_ts/openlayers.py
def add_basemap(
    self,
    basemap: str = "OpenStreetMap",
    attribution: Optional[str] = None,
    **kwargs,
) -> None:
    """Add a basemap layer.

    Args:
        basemap: Name of basemap provider (e.g., "OpenStreetMap", "CartoDB.Positron").
        attribution: Custom attribution text.
        **kwargs: Additional options.
    """
    url, default_attribution = get_basemap_url(basemap)
    self.call_js_method(
        "addBasemap",
        url,
        attribution=attribution or default_attribution,
        name=basemap,
        **kwargs,
    )

    basemaps = self._layer_dict.get("Basemaps", [])
    if basemap not in basemaps:
        self._layer_dict = {
            **self._layer_dict,
            "Basemaps": basemaps + [basemap],
        }

add_control(self, control_type, position='top-right', **kwargs)

Add a map control.

Parameters:

Name Type Description Default
control_type str

Type of control ('zoom', 'scale', 'fullscreen', etc.).

required
position str

Control position.

'top-right'
**kwargs

Control-specific options.

{}
Source code in anymap_ts/openlayers.py
def add_control(
    self,
    control_type: str,
    position: str = "top-right",
    **kwargs,
) -> None:
    """Add a map control.

    Args:
        control_type: Type of control ('zoom', 'scale', 'fullscreen', etc.).
        position: Control position.
        **kwargs: Control-specific options.
    """
    self.call_js_method("addControl", control_type, position=position, **kwargs)
    self._controls = {
        **self._controls,
        control_type: {"type": control_type, "position": position, **kwargs},
    }

add_geojson(self, data, name=None, style=None, fit_bounds=True, **kwargs)

Add GeoJSON data to the map.

Parameters:

Name Type Description Default
data Union[str, Dict]

GeoJSON dict or URL to GeoJSON file.

required
name Optional[str]

Layer name.

None
style Optional[Dict]

Style configuration dict.

None
fit_bounds bool

Whether to fit map to data bounds.

True
**kwargs

Additional layer options.

{}
Source code in anymap_ts/openlayers.py
def add_geojson(
    self,
    data: Union[str, Dict],
    name: Optional[str] = None,
    style: Optional[Dict] = None,
    fit_bounds: bool = True,
    **kwargs,
) -> None:
    """Add GeoJSON data to the map.

    Args:
        data: GeoJSON dict or URL to GeoJSON file.
        name: Layer name.
        style: Style configuration dict.
        fit_bounds: Whether to fit map to data bounds.
        **kwargs: Additional layer options.
    """
    self.add_vector(
        data,
        name=name,
        style=style,
        fit_bounds=fit_bounds,
        **kwargs,
    )

add_image_wms_layer(self, url, layers, name=None, format='image/png', transparent=True, server_type=None, attribution='', **kwargs)

Add a single-image WMS layer (not tiled).

Parameters:

Name Type Description Default
url str

WMS service URL.

required
layers str

Comma-separated layer names.

required
name Optional[str]

Layer name for the map.

None
format str

Image format (default: image/png).

'image/png'
transparent bool

Whether to request transparent images.

True
server_type Optional[str]

Server type ('mapserver', 'geoserver', 'qgis').

None
attribution str

Attribution text.

''
**kwargs

Additional WMS parameters.

{}
Source code in anymap_ts/openlayers.py
def add_image_wms_layer(
    self,
    url: str,
    layers: str,
    name: Optional[str] = None,
    format: str = "image/png",
    transparent: bool = True,
    server_type: Optional[str] = None,
    attribution: str = "",
    **kwargs,
) -> None:
    """Add a single-image WMS layer (not tiled).

    Args:
        url: WMS service URL.
        layers: Comma-separated layer names.
        name: Layer name for the map.
        format: Image format (default: image/png).
        transparent: Whether to request transparent images.
        server_type: Server type ('mapserver', 'geoserver', 'qgis').
        attribution: Attribution text.
        **kwargs: Additional WMS parameters.
    """
    layer_id = name or f"imagewms-{len(self._layers)}"

    self.call_js_method(
        "addImageWMSLayer",
        url=url,
        layers=layers,
        name=layer_id,
        format=format,
        transparent=transparent,
        serverType=server_type,
        attribution=attribution,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {"id": layer_id, "type": "imagewms"},
    }

add_marker(self, lng, lat, popup=None, color='#3388ff', name=None, **kwargs)

Add a marker to the map.

Parameters:

Name Type Description Default
lng float

Marker longitude.

required
lat float

Marker latitude.

required
popup Optional[str]

Popup content (HTML string).

None
color str

Marker color.

'#3388ff'
name Optional[str]

Marker identifier.

None
**kwargs

Additional options.

{}
Source code in anymap_ts/openlayers.py
def add_marker(
    self,
    lng: float,
    lat: float,
    popup: Optional[str] = None,
    color: str = "#3388ff",
    name: Optional[str] = None,
    **kwargs,
) -> None:
    """Add a marker to the map.

    Args:
        lng: Marker longitude.
        lat: Marker latitude.
        popup: Popup content (HTML string).
        color: Marker color.
        name: Marker identifier.
        **kwargs: Additional options.
    """
    marker_id = name or f"marker-{len(self._layers)}"
    self.call_js_method(
        "addMarker",
        lng,
        lat,
        popup=popup,
        color=color,
        id=marker_id,
        **kwargs,
    )

add_tile_layer(self, url, name=None, attribution='', min_zoom=0, max_zoom=22, opacity=1.0, **kwargs)

Add an XYZ tile layer.

Parameters:

Name Type Description Default
url str

Tile URL template with {x}, {y}, {z} placeholders.

required
name Optional[str]

Layer name.

None
attribution str

Attribution text.

''
min_zoom int

Minimum zoom level.

0
max_zoom int

Maximum zoom level.

22
opacity float

Layer opacity.

1.0
**kwargs

Additional options.

{}
Source code in anymap_ts/openlayers.py
def add_tile_layer(
    self,
    url: str,
    name: Optional[str] = None,
    attribution: str = "",
    min_zoom: int = 0,
    max_zoom: int = 22,
    opacity: float = 1.0,
    **kwargs,
) -> None:
    """Add an XYZ tile layer.

    Args:
        url: Tile URL template with {x}, {y}, {z} placeholders.
        name: Layer name.
        attribution: Attribution text.
        min_zoom: Minimum zoom level.
        max_zoom: Maximum zoom level.
        opacity: Layer opacity.
        **kwargs: Additional options.
    """
    layer_id = name or f"tiles-{len(self._layers)}"

    self.call_js_method(
        "addTileLayer",
        url,
        name=layer_id,
        attribution=attribution,
        minZoom=min_zoom,
        maxZoom=max_zoom,
        opacity=opacity,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {"id": layer_id, "type": "tile"},
    }

add_vector(self, data, name=None, style=None, fit_bounds=True, **kwargs)

Add vector data to the map.

Parameters:

Name Type Description Default
data Any

GeoJSON dict, GeoDataFrame, or path to vector file.

required
name Optional[str]

Layer name.

None
style Optional[Dict]

Style configuration dict.

None
fit_bounds bool

Whether to fit map to data bounds.

True
**kwargs

Additional layer options.

{}
Source code in anymap_ts/openlayers.py
def add_vector(
    self,
    data: Any,
    name: Optional[str] = None,
    style: Optional[Dict] = None,
    fit_bounds: bool = True,
    **kwargs,
) -> None:
    """Add vector data to the map.

    Args:
        data: GeoJSON dict, GeoDataFrame, or path to vector file.
        name: Layer name.
        style: Style configuration dict.
        fit_bounds: Whether to fit map to data bounds.
        **kwargs: Additional layer options.
    """
    geojson = to_geojson(data)
    layer_id = name or f"vector-{len(self._layers)}"

    if style is None:
        style = self._get_default_style(geojson)

    self.call_js_method(
        "addGeoJSON",
        data=geojson,
        name=layer_id,
        style=style,
        fitBounds=fit_bounds,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {"id": layer_id, "type": "vector"},
    }

add_wms_layer(self, url, layers, name=None, format='image/png', transparent=True, server_type=None, attribution='', **kwargs)

Add a WMS tile layer.

Parameters:

Name Type Description Default
url str

WMS service URL.

required
layers str

Comma-separated layer names.

required
name Optional[str]

Layer name for the map.

None
format str

Image format (default: image/png).

'image/png'
transparent bool

Whether to request transparent images.

True
server_type Optional[str]

Server type ('mapserver', 'geoserver', 'qgis').

None
attribution str

Attribution text.

''
**kwargs

Additional WMS parameters.

{}
Source code in anymap_ts/openlayers.py
def add_wms_layer(
    self,
    url: str,
    layers: str,
    name: Optional[str] = None,
    format: str = "image/png",
    transparent: bool = True,
    server_type: Optional[str] = None,
    attribution: str = "",
    **kwargs,
) -> None:
    """Add a WMS tile layer.

    Args:
        url: WMS service URL.
        layers: Comma-separated layer names.
        name: Layer name for the map.
        format: Image format (default: image/png).
        transparent: Whether to request transparent images.
        server_type: Server type ('mapserver', 'geoserver', 'qgis').
        attribution: Attribution text.
        **kwargs: Additional WMS parameters.
    """
    layer_id = name or f"wms-{len(self._layers)}"

    self.call_js_method(
        "addWMSLayer",
        url=url,
        layers=layers,
        name=layer_id,
        format=format,
        transparent=transparent,
        serverType=server_type,
        attribution=attribution,
        **kwargs,
    )

    self._layers = {
        **self._layers,
        layer_id: {"id": layer_id, "type": "wms"},
    }

fit_bounds(self, bounds, padding=50, duration=1000)

Fit the map to bounds.

Parameters:

Name Type Description Default
bounds List[float]

Bounds as [minLng, minLat, maxLng, maxLat].

required
padding int

Padding in pixels.

50
duration int

Animation duration in milliseconds.

1000
Source code in anymap_ts/openlayers.py
def fit_bounds(
    self,
    bounds: List[float],
    padding: int = 50,
    duration: int = 1000,
) -> None:
    """Fit the map to bounds.

    Args:
        bounds: Bounds as [minLng, minLat, maxLng, maxLat].
        padding: Padding in pixels.
        duration: Animation duration in milliseconds.
    """
    self.call_js_method("fitBounds", bounds, padding=padding, duration=duration)

fit_extent(self, extent, padding=50, duration=1000)

Fit the map to an extent (in map projection).

Parameters:

Name Type Description Default
extent List[float]

Extent as [minX, minY, maxX, maxY] in map projection.

required
padding int

Padding in pixels.

50
duration int

Animation duration in milliseconds.

1000
Source code in anymap_ts/openlayers.py
def fit_extent(
    self,
    extent: List[float],
    padding: int = 50,
    duration: int = 1000,
) -> None:
    """Fit the map to an extent (in map projection).

    Args:
        extent: Extent as [minX, minY, maxX, maxY] in map projection.
        padding: Padding in pixels.
        duration: Animation duration in milliseconds.
    """
    self.call_js_method("fitExtent", extent, padding=padding, duration=duration)

fly_to(self, lng, lat, zoom=None, duration=2000)

Animate to a new location.

Parameters:

Name Type Description Default
lng float

Target longitude.

required
lat float

Target latitude.

required
zoom Optional[float]

Target zoom level (optional).

None
duration int

Animation duration in milliseconds.

2000
Source code in anymap_ts/openlayers.py
def fly_to(
    self,
    lng: float,
    lat: float,
    zoom: Optional[float] = None,
    duration: int = 2000,
) -> None:
    """Animate to a new location.

    Args:
        lng: Target longitude.
        lat: Target latitude.
        zoom: Target zoom level (optional).
        duration: Animation duration in milliseconds.
    """
    self.call_js_method(
        "flyTo", lng, lat, zoom=zoom or self.zoom, duration=duration
    )

remove_control(self, control_type)

Remove a map control.

Parameters:

Name Type Description Default
control_type str

Type of control to remove.

required
Source code in anymap_ts/openlayers.py
def remove_control(self, control_type: str) -> None:
    """Remove a map control.

    Args:
        control_type: Type of control to remove.
    """
    self.call_js_method("removeControl", control_type)
    if control_type in self._controls:
        controls = dict(self._controls)
        del controls[control_type]
        self._controls = controls

remove_layer(self, layer_id)

Remove a layer from the map.

Parameters:

Name Type Description Default
layer_id str

Layer identifier to remove.

required
Source code in anymap_ts/openlayers.py
def remove_layer(self, layer_id: str) -> None:
    """Remove a layer from the map.

    Args:
        layer_id: Layer identifier to remove.
    """
    if layer_id in self._layers:
        layers = dict(self._layers)
        del layers[layer_id]
        self._layers = layers
    self.call_js_method("removeLayer", layer_id)

set_center(self, lng, lat)

Set the map center.

Parameters:

Name Type Description Default
lng float

Longitude.

required
lat float

Latitude.

required
Source code in anymap_ts/openlayers.py
def set_center(self, lng: float, lat: float) -> None:
    """Set the map center.

    Args:
        lng: Longitude.
        lat: Latitude.
    """
    self.center = [lng, lat]
    self.call_js_method("setCenter", lng, lat)

set_opacity(self, layer_id, opacity)

Set layer opacity.

Parameters:

Name Type Description Default
layer_id str

Layer identifier.

required
opacity float

Opacity value between 0 and 1.

required
Source code in anymap_ts/openlayers.py
def set_opacity(self, layer_id: str, opacity: float) -> None:
    """Set layer opacity.

    Args:
        layer_id: Layer identifier.
        opacity: Opacity value between 0 and 1.
    """
    self.call_js_method("setOpacity", layer_id, opacity)

set_visibility(self, layer_id, visible)

Set layer visibility.

Parameters:

Name Type Description Default
layer_id str

Layer identifier.

required
visible bool

Whether layer should be visible.

required
Source code in anymap_ts/openlayers.py
def set_visibility(self, layer_id: str, visible: bool) -> None:
    """Set layer visibility.

    Args:
        layer_id: Layer identifier.
        visible: Whether layer should be visible.
    """
    self.call_js_method("setVisibility", layer_id, visible)

set_zoom(self, zoom)

Set the map zoom level.

Parameters:

Name Type Description Default
zoom float

Zoom level.

required
Source code in anymap_ts/openlayers.py
def set_zoom(self, zoom: float) -> None:
    """Set the map zoom level.

    Args:
        zoom: Zoom level.
    """
    self.zoom = zoom
    self.call_js_method("setZoom", zoom)

potree

Potree point cloud viewer widget implementation.

Potree is loaded via CDN since it's a complex Three.js-based viewer. This implementation provides a Python wrapper for point cloud visualization.

PotreeViewer (MapWidget)

Interactive point cloud viewer using Potree.

Potree is a WebGL-based point cloud renderer for large-scale LiDAR datasets. This class provides a Python interface for loading and visualizing point clouds.

Note: Potree is loaded from CDN due to its complex Three.js dependencies.

Examples:

>>> from anymap_ts import PotreeViewer
>>> viewer = PotreeViewer()
>>> viewer.load_point_cloud("path/to/pointcloud/cloud.js")
>>> viewer
Source code in anymap_ts/potree.py
class PotreeViewer(MapWidget):
    """Interactive point cloud viewer using Potree.

    Potree is a WebGL-based point cloud renderer for large-scale LiDAR
    datasets. This class provides a Python interface for loading and
    visualizing point clouds.

    Note: Potree is loaded from CDN due to its complex Three.js dependencies.

    Example:
        >>> from anymap_ts import PotreeViewer
        >>> viewer = PotreeViewer()
        >>> viewer.load_point_cloud("path/to/pointcloud/cloud.js")
        >>> viewer
    """

    # ESM module for frontend
    _esm = STATIC_DIR / "potree.js"

    # Potree-specific traits
    point_budget = traitlets.Int(1000000).tag(sync=True)
    point_size = traitlets.Float(1.0).tag(sync=True)
    fov = traitlets.Float(60.0).tag(sync=True)
    background = traitlets.Unicode("#000000").tag(sync=True)

    # EDL (Eye Dome Lighting) settings
    edl_enabled = traitlets.Bool(True).tag(sync=True)
    edl_radius = traitlets.Float(1.4).tag(sync=True)
    edl_strength = traitlets.Float(0.4).tag(sync=True)

    # Point clouds
    point_clouds = traitlets.Dict({}).tag(sync=True)

    # Camera
    camera_position = traitlets.List([0, 0, 100]).tag(sync=True)
    camera_target = traitlets.List([0, 0, 0]).tag(sync=True)

    def __init__(
        self,
        width: str = "100%",
        height: str = "600px",
        point_budget: int = 1000000,
        point_size: float = 1.0,
        fov: float = 60.0,
        background: str = "#000000",
        edl_enabled: bool = True,
        **kwargs,
    ):
        """Initialize a Potree viewer.

        Args:
            width: Widget width as CSS string.
            height: Widget height as CSS string.
            point_budget: Maximum number of points to render.
            point_size: Default point size.
            fov: Field of view in degrees.
            background: Background color (hex string).
            edl_enabled: Enable Eye Dome Lighting.
            **kwargs: Additional widget arguments.
        """
        # Potree doesn't use center/zoom like maps
        super().__init__(
            center=[0, 0],
            zoom=1,
            width=width,
            height=height,
            point_budget=point_budget,
            point_size=point_size,
            fov=fov,
            background=background,
            edl_enabled=edl_enabled,
            **kwargs,
        )
        self.point_clouds = {}

    # -------------------------------------------------------------------------
    # Point Cloud Methods
    # -------------------------------------------------------------------------

    def load_point_cloud(
        self,
        url: str,
        name: Optional[str] = None,
        visible: bool = True,
        point_size: Optional[float] = None,
        point_size_type: str = "adaptive",
        shape: str = "circle",
        color: Optional[str] = None,
        **kwargs,
    ) -> None:
        """Load a point cloud.

        Args:
            url: URL to point cloud (Potree format or LAZ/LAS via Entwine).
            name: Point cloud name.
            visible: Whether point cloud is visible.
            point_size: Point size (overrides default).
            point_size_type: 'fixed', 'attenuated', or 'adaptive'.
            shape: Point shape ('square', 'circle', 'paraboloid').
            color: Point color (hex string or None for native colors).
            **kwargs: Additional material options.
        """
        cloud_id = name or f"pointcloud_{len(self.point_clouds)}"

        self.point_clouds = {
            **self.point_clouds,
            cloud_id: {
                "url": url,
                "name": cloud_id,
                "visible": visible,
                "material": {
                    "size": point_size or self.point_size,
                    "pointSizeType": point_size_type,
                    "shape": shape,
                    "color": color,
                    **kwargs,
                },
            },
        }

        self.call_js_method(
            "loadPointCloud",
            url=url,
            name=cloud_id,
            visible=visible,
            material={
                "size": point_size or self.point_size,
                "pointSizeType": point_size_type,
                "shape": shape,
                "color": color,
                **kwargs,
            },
        )

    def remove_point_cloud(self, name: str) -> None:
        """Remove a point cloud.

        Args:
            name: Point cloud name to remove.
        """
        if name in self.point_clouds:
            clouds = dict(self.point_clouds)
            del clouds[name]
            self.point_clouds = clouds
        self.call_js_method("removePointCloud", name=name)

    def set_point_cloud_visibility(self, name: str, visible: bool) -> None:
        """Set point cloud visibility.

        Args:
            name: Point cloud name.
            visible: Whether to show the point cloud.
        """
        self.call_js_method("setPointCloudVisibility", name=name, visible=visible)

    # -------------------------------------------------------------------------
    # Camera Methods
    # -------------------------------------------------------------------------

    def set_camera_position(
        self,
        x: float,
        y: float,
        z: float,
    ) -> None:
        """Set camera position.

        Args:
            x: X coordinate.
            y: Y coordinate.
            z: Z coordinate.
        """
        self.camera_position = [x, y, z]
        self.call_js_method("setCameraPosition", x=x, y=y, z=z)

    def set_camera_target(
        self,
        x: float,
        y: float,
        z: float,
    ) -> None:
        """Set camera target (look-at point).

        Args:
            x: X coordinate.
            y: Y coordinate.
            z: Z coordinate.
        """
        self.camera_target = [x, y, z]
        self.call_js_method("setCameraTarget", x=x, y=y, z=z)

    def fly_to_point_cloud(self, name: Optional[str] = None) -> None:
        """Fly to a point cloud or all point clouds.

        Args:
            name: Point cloud name (None for all).
        """
        self.call_js_method("flyToPointCloud", name=name)

    def reset_camera(self) -> None:
        """Reset camera to default view."""
        self.call_js_method("resetCamera")

    # -------------------------------------------------------------------------
    # Visualization Settings
    # -------------------------------------------------------------------------

    def set_point_budget(self, budget: int) -> None:
        """Set the point budget (max points to render).

        Args:
            budget: Maximum number of points.
        """
        self.point_budget = budget
        self.call_js_method("setPointBudget", budget=budget)

    def set_point_size(self, size: float) -> None:
        """Set default point size.

        Args:
            size: Point size.
        """
        self.point_size = size
        self.call_js_method("setPointSize", size=size)

    def set_fov(self, fov: float) -> None:
        """Set field of view.

        Args:
            fov: Field of view in degrees.
        """
        self.fov = fov
        self.call_js_method("setFOV", fov=fov)

    def set_background(self, color: str) -> None:
        """Set background color.

        Args:
            color: Background color (hex string).
        """
        self.background = color
        self.call_js_method("setBackground", color=color)

    def set_edl(
        self,
        enabled: bool = True,
        radius: float = 1.4,
        strength: float = 0.4,
    ) -> None:
        """Configure Eye Dome Lighting.

        Args:
            enabled: Whether to enable EDL.
            radius: EDL radius.
            strength: EDL strength.
        """
        self.edl_enabled = enabled
        self.edl_radius = radius
        self.edl_strength = strength
        self.call_js_method(
            "setEDL",
            enabled=enabled,
            radius=radius,
            strength=strength,
        )

    # -------------------------------------------------------------------------
    # Measurement Tools
    # -------------------------------------------------------------------------

    def add_measurement_tool(self, tool_type: str = "distance") -> None:
        """Add a measurement tool.

        Args:
            tool_type: Type of measurement ('point', 'distance', 'area', 'angle', 'height', 'profile').
        """
        self.call_js_method("addMeasurementTool", type=tool_type)

    def clear_measurements(self) -> None:
        """Clear all measurements."""
        self.call_js_method("clearMeasurements")

    # -------------------------------------------------------------------------
    # Clipping
    # -------------------------------------------------------------------------

    def add_clipping_volume(
        self,
        volume_type: str = "box",
        position: Optional[Tuple[float, float, float]] = None,
        scale: Optional[Tuple[float, float, float]] = None,
    ) -> None:
        """Add a clipping volume.

        Args:
            volume_type: Type of volume ('box', 'polygon', 'plane').
            position: Volume position (x, y, z).
            scale: Volume scale (x, y, z).
        """
        self.call_js_method(
            "addClippingVolume",
            type=volume_type,
            position=list(position) if position else None,
            scale=list(scale) if scale else None,
        )

    def clear_clipping_volumes(self) -> None:
        """Clear all clipping volumes."""
        self.call_js_method("clearClippingVolumes")

    # -------------------------------------------------------------------------
    # Annotations
    # -------------------------------------------------------------------------

    def add_annotation(
        self,
        position: Tuple[float, float, float],
        title: str,
        description: str = "",
        camera_position: Optional[Tuple[float, float, float]] = None,
        camera_target: Optional[Tuple[float, float, float]] = None,
    ) -> None:
        """Add an annotation.

        Args:
            position: Annotation position (x, y, z).
            title: Annotation title.
            description: Annotation description.
            camera_position: Camera position when focused.
            camera_target: Camera target when focused.
        """
        self.call_js_method(
            "addAnnotation",
            position=list(position),
            title=title,
            description=description,
            cameraPosition=list(camera_position) if camera_position else None,
            cameraTarget=list(camera_target) if camera_target else None,
        )

    def clear_annotations(self) -> None:
        """Clear all annotations."""
        self.call_js_method("clearAnnotations")

    # -------------------------------------------------------------------------
    # HTML Export
    # -------------------------------------------------------------------------

    def _generate_html_template(self) -> str:
        """Generate standalone HTML for Potree viewer."""
        template_path = Path(__file__).parent / "templates" / "potree.html"

        if template_path.exists():
            template = template_path.read_text(encoding="utf-8")
        else:
            template = self._get_default_template()

        state = {
            "point_budget": self.point_budget,
            "point_size": self.point_size,
            "fov": self.fov,
            "background": self.background,
            "edl_enabled": self.edl_enabled,
            "edl_radius": self.edl_radius,
            "edl_strength": self.edl_strength,
            "point_clouds": self.point_clouds,
            "camera_position": self.camera_position,
            "camera_target": self.camera_target,
            "width": self.width,
            "height": self.height,
            "js_calls": self._js_calls,
        }

        template = template.replace("{{state}}", json.dumps(state, indent=2))
        return template

    def _get_default_template(self) -> str:
        """Get default HTML template."""
        return """<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>Potree Viewer</title>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <style>
        * { margin: 0; padding: 0; box-sizing: border-box; }
        html, body { height: 100%; overflow: hidden; }
        #potree_render_area { position: absolute; top: 0; bottom: 0; width: 100%; }
    </style>
</head>
<body>
    <div id="potree_render_area"></div>
    <script>
        const state = {{state}};
        document.getElementById('potree_render_area').innerHTML = '<p style="color: white; padding: 20px;">Potree viewer requires Potree library. Point clouds: ' + Object.keys(state.point_clouds || {}).length + '</p>';
    </script>
</body>
</html>"""

__init__(self, width='100%', height='600px', point_budget=1000000, point_size=1.0, fov=60.0, background='#000000', edl_enabled=True, **kwargs) special

Initialize a Potree viewer.

Parameters:

Name Type Description Default
width str

Widget width as CSS string.

'100%'
height str

Widget height as CSS string.

'600px'
point_budget int

Maximum number of points to render.

1000000
point_size float

Default point size.

1.0
fov float

Field of view in degrees.

60.0
background str

Background color (hex string).

'#000000'
edl_enabled bool

Enable Eye Dome Lighting.

True
**kwargs

Additional widget arguments.

{}
Source code in anymap_ts/potree.py
def __init__(
    self,
    width: str = "100%",
    height: str = "600px",
    point_budget: int = 1000000,
    point_size: float = 1.0,
    fov: float = 60.0,
    background: str = "#000000",
    edl_enabled: bool = True,
    **kwargs,
):
    """Initialize a Potree viewer.

    Args:
        width: Widget width as CSS string.
        height: Widget height as CSS string.
        point_budget: Maximum number of points to render.
        point_size: Default point size.
        fov: Field of view in degrees.
        background: Background color (hex string).
        edl_enabled: Enable Eye Dome Lighting.
        **kwargs: Additional widget arguments.
    """
    # Potree doesn't use center/zoom like maps
    super().__init__(
        center=[0, 0],
        zoom=1,
        width=width,
        height=height,
        point_budget=point_budget,
        point_size=point_size,
        fov=fov,
        background=background,
        edl_enabled=edl_enabled,
        **kwargs,
    )
    self.point_clouds = {}

add_annotation(self, position, title, description='', camera_position=None, camera_target=None)

Add an annotation.

Parameters:

Name Type Description Default
position Tuple[float, float, float]

Annotation position (x, y, z).

required
title str

Annotation title.

required
description str

Annotation description.

''
camera_position Optional[Tuple[float, float, float]]

Camera position when focused.

None
camera_target Optional[Tuple[float, float, float]]

Camera target when focused.

None
Source code in anymap_ts/potree.py
def add_annotation(
    self,
    position: Tuple[float, float, float],
    title: str,
    description: str = "",
    camera_position: Optional[Tuple[float, float, float]] = None,
    camera_target: Optional[Tuple[float, float, float]] = None,
) -> None:
    """Add an annotation.

    Args:
        position: Annotation position (x, y, z).
        title: Annotation title.
        description: Annotation description.
        camera_position: Camera position when focused.
        camera_target: Camera target when focused.
    """
    self.call_js_method(
        "addAnnotation",
        position=list(position),
        title=title,
        description=description,
        cameraPosition=list(camera_position) if camera_position else None,
        cameraTarget=list(camera_target) if camera_target else None,
    )

add_clipping_volume(self, volume_type='box', position=None, scale=None)

Add a clipping volume.

Parameters:

Name Type Description Default
volume_type str

Type of volume ('box', 'polygon', 'plane').

'box'
position Optional[Tuple[float, float, float]]

Volume position (x, y, z).

None
scale Optional[Tuple[float, float, float]]

Volume scale (x, y, z).

None
Source code in anymap_ts/potree.py
def add_clipping_volume(
    self,
    volume_type: str = "box",
    position: Optional[Tuple[float, float, float]] = None,
    scale: Optional[Tuple[float, float, float]] = None,
) -> None:
    """Add a clipping volume.

    Args:
        volume_type: Type of volume ('box', 'polygon', 'plane').
        position: Volume position (x, y, z).
        scale: Volume scale (x, y, z).
    """
    self.call_js_method(
        "addClippingVolume",
        type=volume_type,
        position=list(position) if position else None,
        scale=list(scale) if scale else None,
    )

add_measurement_tool(self, tool_type='distance')

Add a measurement tool.

Parameters:

Name Type Description Default
tool_type str

Type of measurement ('point', 'distance', 'area', 'angle', 'height', 'profile').

'distance'
Source code in anymap_ts/potree.py
def add_measurement_tool(self, tool_type: str = "distance") -> None:
    """Add a measurement tool.

    Args:
        tool_type: Type of measurement ('point', 'distance', 'area', 'angle', 'height', 'profile').
    """
    self.call_js_method("addMeasurementTool", type=tool_type)

clear_annotations(self)

Clear all annotations.

Source code in anymap_ts/potree.py
def clear_annotations(self) -> None:
    """Clear all annotations."""
    self.call_js_method("clearAnnotations")

clear_clipping_volumes(self)

Clear all clipping volumes.

Source code in anymap_ts/potree.py
def clear_clipping_volumes(self) -> None:
    """Clear all clipping volumes."""
    self.call_js_method("clearClippingVolumes")

clear_measurements(self)

Clear all measurements.

Source code in anymap_ts/potree.py
def clear_measurements(self) -> None:
    """Clear all measurements."""
    self.call_js_method("clearMeasurements")

fly_to_point_cloud(self, name=None)

Fly to a point cloud or all point clouds.

Parameters:

Name Type Description Default
name Optional[str]

Point cloud name (None for all).

None
Source code in anymap_ts/potree.py
def fly_to_point_cloud(self, name: Optional[str] = None) -> None:
    """Fly to a point cloud or all point clouds.

    Args:
        name: Point cloud name (None for all).
    """
    self.call_js_method("flyToPointCloud", name=name)

load_point_cloud(self, url, name=None, visible=True, point_size=None, point_size_type='adaptive', shape='circle', color=None, **kwargs)

Load a point cloud.

Parameters:

Name Type Description Default
url str

URL to point cloud (Potree format or LAZ/LAS via Entwine).

required
name Optional[str]

Point cloud name.

None
visible bool

Whether point cloud is visible.

True
point_size Optional[float]

Point size (overrides default).

None
point_size_type str

'fixed', 'attenuated', or 'adaptive'.

'adaptive'
shape str

Point shape ('square', 'circle', 'paraboloid').

'circle'
color Optional[str]

Point color (hex string or None for native colors).

None
**kwargs

Additional material options.

{}
Source code in anymap_ts/potree.py
def load_point_cloud(
    self,
    url: str,
    name: Optional[str] = None,
    visible: bool = True,
    point_size: Optional[float] = None,
    point_size_type: str = "adaptive",
    shape: str = "circle",
    color: Optional[str] = None,
    **kwargs,
) -> None:
    """Load a point cloud.

    Args:
        url: URL to point cloud (Potree format or LAZ/LAS via Entwine).
        name: Point cloud name.
        visible: Whether point cloud is visible.
        point_size: Point size (overrides default).
        point_size_type: 'fixed', 'attenuated', or 'adaptive'.
        shape: Point shape ('square', 'circle', 'paraboloid').
        color: Point color (hex string or None for native colors).
        **kwargs: Additional material options.
    """
    cloud_id = name or f"pointcloud_{len(self.point_clouds)}"

    self.point_clouds = {
        **self.point_clouds,
        cloud_id: {
            "url": url,
            "name": cloud_id,
            "visible": visible,
            "material": {
                "size": point_size or self.point_size,
                "pointSizeType": point_size_type,
                "shape": shape,
                "color": color,
                **kwargs,
            },
        },
    }

    self.call_js_method(
        "loadPointCloud",
        url=url,
        name=cloud_id,
        visible=visible,
        material={
            "size": point_size or self.point_size,
            "pointSizeType": point_size_type,
            "shape": shape,
            "color": color,
            **kwargs,
        },
    )

remove_point_cloud(self, name)

Remove a point cloud.

Parameters:

Name Type Description Default
name str

Point cloud name to remove.

required
Source code in anymap_ts/potree.py
def remove_point_cloud(self, name: str) -> None:
    """Remove a point cloud.

    Args:
        name: Point cloud name to remove.
    """
    if name in self.point_clouds:
        clouds = dict(self.point_clouds)
        del clouds[name]
        self.point_clouds = clouds
    self.call_js_method("removePointCloud", name=name)

reset_camera(self)

Reset camera to default view.

Source code in anymap_ts/potree.py
def reset_camera(self) -> None:
    """Reset camera to default view."""
    self.call_js_method("resetCamera")

set_background(self, color)

Set background color.

Parameters:

Name Type Description Default
color str

Background color (hex string).

required
Source code in anymap_ts/potree.py
def set_background(self, color: str) -> None:
    """Set background color.

    Args:
        color: Background color (hex string).
    """
    self.background = color
    self.call_js_method("setBackground", color=color)

set_camera_position(self, x, y, z)

Set camera position.

Parameters:

Name Type Description Default
x float

X coordinate.

required
y float

Y coordinate.

required
z float

Z coordinate.

required
Source code in anymap_ts/potree.py
def set_camera_position(
    self,
    x: float,
    y: float,
    z: float,
) -> None:
    """Set camera position.

    Args:
        x: X coordinate.
        y: Y coordinate.
        z: Z coordinate.
    """
    self.camera_position = [x, y, z]
    self.call_js_method("setCameraPosition", x=x, y=y, z=z)

set_camera_target(self, x, y, z)

Set camera target (look-at point).

Parameters:

Name Type Description Default
x float

X coordinate.

required
y float

Y coordinate.

required
z float

Z coordinate.

required
Source code in anymap_ts/potree.py
def set_camera_target(
    self,
    x: float,
    y: float,
    z: float,
) -> None:
    """Set camera target (look-at point).

    Args:
        x: X coordinate.
        y: Y coordinate.
        z: Z coordinate.
    """
    self.camera_target = [x, y, z]
    self.call_js_method("setCameraTarget", x=x, y=y, z=z)

set_edl(self, enabled=True, radius=1.4, strength=0.4)

Configure Eye Dome Lighting.

Parameters:

Name Type Description Default
enabled bool

Whether to enable EDL.

True
radius float

EDL radius.

1.4
strength float

EDL strength.

0.4
Source code in anymap_ts/potree.py
def set_edl(
    self,
    enabled: bool = True,
    radius: float = 1.4,
    strength: float = 0.4,
) -> None:
    """Configure Eye Dome Lighting.

    Args:
        enabled: Whether to enable EDL.
        radius: EDL radius.
        strength: EDL strength.
    """
    self.edl_enabled = enabled
    self.edl_radius = radius
    self.edl_strength = strength
    self.call_js_method(
        "setEDL",
        enabled=enabled,
        radius=radius,
        strength=strength,
    )

set_fov(self, fov)

Set field of view.

Parameters:

Name Type Description Default
fov float

Field of view in degrees.

required
Source code in anymap_ts/potree.py
def set_fov(self, fov: float) -> None:
    """Set field of view.

    Args:
        fov: Field of view in degrees.
    """
    self.fov = fov
    self.call_js_method("setFOV", fov=fov)

set_point_budget(self, budget)

Set the point budget (max points to render).

Parameters:

Name Type Description Default
budget int

Maximum number of points.

required
Source code in anymap_ts/potree.py
def set_point_budget(self, budget: int) -> None:
    """Set the point budget (max points to render).

    Args:
        budget: Maximum number of points.
    """
    self.point_budget = budget
    self.call_js_method("setPointBudget", budget=budget)

set_point_cloud_visibility(self, name, visible)

Set point cloud visibility.

Parameters:

Name Type Description Default
name str

Point cloud name.

required
visible bool

Whether to show the point cloud.

required
Source code in anymap_ts/potree.py
def set_point_cloud_visibility(self, name: str, visible: bool) -> None:
    """Set point cloud visibility.

    Args:
        name: Point cloud name.
        visible: Whether to show the point cloud.
    """
    self.call_js_method("setPointCloudVisibility", name=name, visible=visible)

set_point_size(self, size)

Set default point size.

Parameters:

Name Type Description Default
size float

Point size.

required
Source code in anymap_ts/potree.py
def set_point_size(self, size: float) -> None:
    """Set default point size.

    Args:
        size: Point size.
    """
    self.point_size = size
    self.call_js_method("setPointSize", size=size)

utils

Utility functions for anymap-ts.

build_step_expression(column, breaks, colors)

Build a MapLibre step expression for choropleth styling.

Parameters:

Name Type Description Default
column str

Property name to style by.

required
breaks List[float]

Break values (k+1 values for k classes).

required
colors List[str]

List of k colors for each class.

required

Returns:

Type Description
List

MapLibre step expression as a list.

Source code in anymap_ts/utils.py
def build_step_expression(column: str, breaks: List[float], colors: List[str]) -> List:
    """Build a MapLibre step expression for choropleth styling.

    Args:
        column: Property name to style by.
        breaks: Break values (k+1 values for k classes).
        colors: List of k colors for each class.

    Returns:
        MapLibre step expression as a list.
    """
    # MapLibre step expression format:
    # ["step", ["get", "property"], color0, break1, color1, break2, color2, ...]
    expr = ["step", ["get", column], colors[0]]

    # Add breaks and colors (skip the first break which is the minimum)
    for i in range(1, len(breaks) - 1):
        expr.append(breaks[i])
        expr.append(colors[i])

    # Handle the last class
    if len(colors) > len(breaks) - 1:
        expr.append(breaks[-1])
        expr.append(colors[-1])

    return expr

compute_breaks(values, classification, k, manual_breaks=None)

Compute classification breaks for choropleth maps.

Parameters:

Name Type Description Default
values List[float]

List of numeric values to classify.

required
classification str

Classification method ('quantile', 'equal_interval', 'natural_breaks', 'manual').

required
k int

Number of classes.

required
manual_breaks Optional[List[float]]

Custom break values for 'manual' classification.

None

Returns:

Type Description
List[float]

List of break values (k+1 values defining class boundaries).

Exceptions:

Type Description
ValueError

If classification method is invalid or breaks are incorrect.

Source code in anymap_ts/utils.py
def compute_breaks(
    values: List[float],
    classification: str,
    k: int,
    manual_breaks: Optional[List[float]] = None,
) -> List[float]:
    """Compute classification breaks for choropleth maps.

    Args:
        values: List of numeric values to classify.
        classification: Classification method ('quantile', 'equal_interval',
            'natural_breaks', 'manual').
        k: Number of classes.
        manual_breaks: Custom break values for 'manual' classification.

    Returns:
        List of break values (k+1 values defining class boundaries).

    Raises:
        ValueError: If classification method is invalid or breaks are incorrect.
    """
    if classification == "manual":
        if manual_breaks is None:
            raise ValueError("manual_breaks required for 'manual' classification")
        if len(manual_breaks) != k + 1:
            raise ValueError(f"manual_breaks must have {k + 1} values for {k} classes")
        return manual_breaks

    sorted_values = sorted(values)
    min_val = sorted_values[0]
    max_val = sorted_values[-1]

    if classification == "quantile":
        # Equal number of features per class
        breaks = [min_val]
        for i in range(1, k):
            idx = int(len(sorted_values) * i / k)
            breaks.append(sorted_values[idx])
        breaks.append(max_val)
        return breaks

    elif classification == "equal_interval":
        # Equal value ranges
        interval = (max_val - min_val) / k
        breaks = [min_val + i * interval for i in range(k + 1)]
        return breaks

    elif classification == "natural_breaks":
        # Jenks natural breaks - requires jenkspy
        try:
            import jenkspy

            breaks = jenkspy.jenks_breaks(values, n_classes=k)
            return breaks
        except ImportError:
            raise ImportError(
                "jenkspy is required for natural_breaks classification. "
                "Install with: pip install jenkspy"
            )

    else:
        raise ValueError(
            f"Unknown classification method '{classification}'. "
            "Options: 'quantile', 'equal_interval', 'natural_breaks', 'manual'"
        )

fetch_geojson(url)

Fetch GeoJSON data from a URL.

Parameters:

Name Type Description Default
url str

URL to fetch GeoJSON from

required

Returns:

Type Description
Dict

GeoJSON dict

Exceptions:

Type Description
ValueError

If the URL cannot be fetched or parsed

Source code in anymap_ts/utils.py
def fetch_geojson(url: str) -> Dict:
    """Fetch GeoJSON data from a URL.

    Args:
        url: URL to fetch GeoJSON from

    Returns:
        GeoJSON dict

    Raises:
        ValueError: If the URL cannot be fetched or parsed
    """
    try:
        with urlopen(url, timeout=30) as response:
            charset = response.headers.get_content_charset() or "utf-8"
            data = response.read().decode(charset)
            return json.loads(data)
    except URLError as e:
        raise ValueError(f"Failed to fetch GeoJSON from URL: {e}") from e
    except UnicodeDecodeError as e:
        raise ValueError(f"Failed to decode response as UTF-8: {e}") from e
    except json.JSONDecodeError as e:
        raise ValueError(f"Invalid JSON at URL: {e}") from e

get_bounds(data)

Calculate bounds from GeoJSON or GeoDataFrame.

Parameters:

Name Type Description Default
data Any

GeoJSON dict or GeoDataFrame

required

Returns:

Type Description
Optional[List[float]]

[west, south, east, north] bounds or None

Source code in anymap_ts/utils.py
def get_bounds(data: Any) -> Optional[List[float]]:
    """Calculate bounds from GeoJSON or GeoDataFrame.

    Args:
        data: GeoJSON dict or GeoDataFrame

    Returns:
        [west, south, east, north] bounds or None
    """
    if HAS_GEOPANDAS and isinstance(data, gpd.GeoDataFrame):
        bounds = data.total_bounds
        return [bounds[0], bounds[1], bounds[2], bounds[3]]

    if isinstance(data, dict):
        if HAS_SHAPELY:
            return _get_geojson_bounds_shapely(data)
        return _get_geojson_bounds_simple(data)

    return None

get_choropleth_colors(cmap, k)

Get colors for a choropleth map using matplotlib colormaps.

Uses matplotlib colormaps when available, falling back to a small set of built-in colormaps if matplotlib is not installed.

Parameters:

Name Type Description Default
cmap str

Colormap name. Any matplotlib colormap is supported when matplotlib is installed. Common options include: - Sequential: 'viridis', 'plasma', 'inferno', 'magma', 'cividis', 'Blues', 'Greens', 'Reds', 'Oranges', 'Purples', 'Greys' - Diverging: 'RdBu', 'RdYlGn', 'RdYlBu', 'Spectral', 'coolwarm', 'bwr', 'seismic' - Qualitative: 'Set1', 'Set2', 'Set3', 'Paired', 'tab10', 'tab20' - Perceptually uniform: 'viridis', 'plasma', 'inferno', 'magma'

required
k int

Number of classes/colors to generate.

required

Returns:

Type Description
List[str]

List of k hex color strings.

Exceptions:

Type Description
ValueError

If colormap is not found.

Examples:

>>> colors = get_choropleth_colors('viridis', 5)
>>> colors
['#440154', '#3b528b', '#21918c', '#5ec962', '#fde725']
Source code in anymap_ts/utils.py
def get_choropleth_colors(cmap: str, k: int) -> List[str]:
    """Get colors for a choropleth map using matplotlib colormaps.

    Uses matplotlib colormaps when available, falling back to a small
    set of built-in colormaps if matplotlib is not installed.

    Args:
        cmap: Colormap name. Any matplotlib colormap is supported when
            matplotlib is installed. Common options include:
            - Sequential: 'viridis', 'plasma', 'inferno', 'magma', 'cividis',
              'Blues', 'Greens', 'Reds', 'Oranges', 'Purples', 'Greys'
            - Diverging: 'RdBu', 'RdYlGn', 'RdYlBu', 'Spectral', 'coolwarm',
              'bwr', 'seismic'
            - Qualitative: 'Set1', 'Set2', 'Set3', 'Paired', 'tab10', 'tab20'
            - Perceptually uniform: 'viridis', 'plasma', 'inferno', 'magma'
        k: Number of classes/colors to generate.

    Returns:
        List of k hex color strings.

    Raises:
        ValueError: If colormap is not found.

    Example:
        >>> colors = get_choropleth_colors('viridis', 5)
        >>> colors
        ['#440154', '#3b528b', '#21918c', '#5ec962', '#fde725']
    """
    if HAS_MATPLOTLIB:
        try:
            # Get the colormap from matplotlib
            colormap = plt.get_cmap(cmap)

            # Sample k colors evenly from the colormap
            colors = []
            for i in range(k):
                # Sample at evenly spaced points
                position = i / (k - 1) if k > 1 else 0.5
                rgba = colormap(position)
                colors.append(_rgb_to_hex(rgba))

            return colors

        except ValueError:
            raise ValueError(
                f"Unknown colormap '{cmap}'. See matplotlib colormap documentation "
                "for available options: https://matplotlib.org/stable/gallery/color/colormap_reference.html"
            )
    else:
        # Fallback to built-in colormaps
        if cmap not in _FALLBACK_COLORMAPS:
            available = ", ".join(sorted(_FALLBACK_COLORMAPS.keys()))
            raise ValueError(
                f"Colormap '{cmap}' not available. Without matplotlib, only these "
                f"colormaps are available: {available}. "
                "Install matplotlib for full colormap support: pip install matplotlib"
            )

        full_colors = _FALLBACK_COLORMAPS[cmap]

        if k <= len(full_colors):
            # Sample evenly from the colormap
            step = len(full_colors) / k
            indices = [int(i * step) for i in range(k)]
            return [full_colors[i] for i in indices]
        else:
            # Interpolate if we need more colors than available
            # For simplicity, just repeat the last colors
            colors = full_colors[:]
            while len(colors) < k:
                colors.append(colors[-1])
            return colors[:k]

get_default_paint(layer_type)

Get default paint properties for a layer type.

Parameters:

Name Type Description Default
layer_type str

MapLibre layer type

required

Returns:

Type Description
Dict[str, Any]

Paint properties dict

Source code in anymap_ts/utils.py
def get_default_paint(layer_type: str) -> Dict[str, Any]:
    """Get default paint properties for a layer type.

    Args:
        layer_type: MapLibre layer type

    Returns:
        Paint properties dict
    """
    defaults = {
        "circle": {
            "circle-radius": 5,
            "circle-color": "#3388ff",
            "circle-opacity": 0.8,
            "circle-stroke-width": 1,
            "circle-stroke-color": "#ffffff",
        },
        "line": {
            "line-color": "#3388ff",
            "line-width": 2,
            "line-opacity": 0.8,
        },
        "fill": {
            "fill-color": "#3388ff",
            "fill-opacity": 0.5,
            "fill-outline-color": "#0000ff",
        },
        "fill-extrusion": {
            "fill-extrusion-color": "#3388ff",
            "fill-extrusion-opacity": 0.6,
            "fill-extrusion-height": 100,
        },
        "raster": {
            "raster-opacity": 1,
        },
        "heatmap": {
            "heatmap-opacity": 0.8,
        },
    }
    return defaults.get(layer_type, {})

infer_layer_type(geojson)

Infer MapLibre layer type from GeoJSON geometry.

Parameters:

Name Type Description Default
geojson Dict

GeoJSON dict

required

Returns:

Type Description
str

Layer type ('circle', 'line', 'fill')

Source code in anymap_ts/utils.py
def infer_layer_type(geojson: Dict) -> str:
    """Infer MapLibre layer type from GeoJSON geometry.

    Args:
        geojson: GeoJSON dict

    Returns:
        Layer type ('circle', 'line', 'fill')
    """
    geometry_type = None

    if geojson.get("type") == "FeatureCollection":
        features = geojson.get("features", [])
        if features:
            geometry_type = features[0].get("geometry", {}).get("type")
    elif geojson.get("type") == "Feature":
        geometry_type = geojson.get("geometry", {}).get("type")
    else:
        geometry_type = geojson.get("type")

    type_map = {
        "Point": "circle",
        "MultiPoint": "circle",
        "LineString": "line",
        "MultiLineString": "line",
        "Polygon": "fill",
        "MultiPolygon": "fill",
        "GeometryCollection": "fill",
    }

    return type_map.get(geometry_type, "circle")

to_geojson(data)

Convert various data formats to GeoJSON.

Parameters:

Name Type Description Default
data Any

GeoJSON dict, GeoDataFrame, file path, or URL

required

Returns:

Type Description
Dict

GeoJSON dict

Exceptions:

Type Description
ValueError

If data cannot be converted

ImportError

If geopandas is required but not installed

Source code in anymap_ts/utils.py
def to_geojson(data: Any) -> Dict:
    """Convert various data formats to GeoJSON.

    Args:
        data: GeoJSON dict, GeoDataFrame, file path, or URL

    Returns:
        GeoJSON dict

    Raises:
        ValueError: If data cannot be converted
        ImportError: If geopandas is required but not installed
    """
    # Already a dict (GeoJSON)
    if isinstance(data, dict):
        return data

    # GeoDataFrame
    if HAS_GEOPANDAS and isinstance(data, gpd.GeoDataFrame):
        return json.loads(data.to_json())

    # File path or URL
    if isinstance(data, (str, Path)):
        path_str = str(data)

        # If it's a URL, return as-is (will be handled by JS)
        if path_str.startswith(("http://", "https://")):
            return {"type": "url", "url": path_str}

        # Read file with geopandas
        if not HAS_GEOPANDAS:
            raise ImportError(
                "geopandas is required to read vector files. "
                "Install with: pip install anymap-ts[vector]"
            )

        gdf = gpd.read_file(path_str)
        return json.loads(gdf.to_json())

    # Has __geo_interface__ (shapely geometry, etc.)
    if hasattr(data, "__geo_interface__"):
        geo = data.__geo_interface__
        if geo.get("type") in (
            "Point",
            "LineString",
            "Polygon",
            "MultiPoint",
            "MultiLineString",
            "MultiPolygon",
            "GeometryCollection",
        ):
            return {"type": "Feature", "geometry": geo, "properties": {}}
        return geo

    raise ValueError(f"Cannot convert {type(data)} to GeoJSON")